Irisity Alarm Filter Beta supports SMTP and HTTPS as the main ways of connecting to the system. Other custom integrations may be added at a later date.

The SMTP server in the camera/NVR/... needs to be set to point to the Irisity Alarm Filter one. Authentication details are provided separately by Irisity.

An example can be found below:

  To: <see details below>@alarmfilter.irisity.io   From: <any-valid-email>   Username: <given by Irisity>   Password: <given by Irisity>   Email Server (SMTP): s.alarmfilter.irisity.io   Port: 587   Encryption: TLS

To send alarms via HTTPS, a valid URL and authentication need to be set up in camera/NVR/...

Authentication is done through an API-KEY which is provided separately by Irisity. The API-KEY can be provided through the HTTP header X-API-KEY or through a query parameter ‘apikey’ in the request. Notice that passing the API-KEY through the http-header is preferred as this does not expose the API-KEY, however, not all cameras/NVRs support this.

An example can be found below:

  URL: https://in.alarmfilter.irisity.io   Port: 443   API-KEY: <given by Irisity>   

Each alarm sent to the alarm filter must contain either a short video clip (preferred) or multiple image frames that jointly make up a video sequence from a surveillance camera. This video or image sequence will be called video, video clip, and clip, interchangeably.

The video or separate images should be at least three frames long, preferably 6-10 frames. At least three images/frames are required for the filter to detect motion in the video.

Based on the video clip, each incoming alarm video will be classified as either a True alarm or a False alarm.

For SMTP, the video or images are sent as attachments to the email. For HTTPS, the video or images are sent through the body of the HTTP request.

True alarms are alarms that contain human activity, meaning people or vehicles moving.

False alarms are other alarms.

You can expect the Irisity Alarm Filter to filter out more than 95% of all incoming False alarms while removing very few True alarms.

The incoming email service will parse incoming emails using one of multiple API providers. If no specific API is specific, the Generic provider will be used.

Currently, these providers exist for SMTP:

The following providers exist for HTTPS:

The details of each API will be detailed in the following sections.

The main goal of the parsing is to tie each incoming alarm to a unique incoming ID. Each camera needs to have a unique incoming ID. Depending on the API used and the parameters sent, this unique name will be either assigned (most common) or explicitly set. The incoming id will always be calculated for each incoming alarm, and we recommend where possible to set it explicitly. Examples of setting the incoming camera id explicitly:

The main method of parsing emails starts with the recipient (to) address of the email. This is because most surveillance cameras and network equipment have very limited support for user-definable data and parameters anywhere else. Depending on the API used special parsing may be done that uses other fields, such as the email body or attachments.

The main method of parsing HTTP requests is done by passing in query parameters in the HTTP query request.

In the documentation below square bracket [...] will be used to show template variables and user-definable input. [camera-incoming-id] means that the unique ID of that camera is expected, an example provided by a user could be camera-841748. Note that the square brackets should be omitted when transforming the templates to the real world.

Specific API parameters are given in the [key]=[value] format. Keys are always transformed to lowercase, meaning casing typically does not matter.

The simplest way to set up cameras for easy integration with IMMIX is to make the incoming camera ID match IMMIX's IDs. IMMIX supports three different identifiers:

The most typical example would be to specify S-number and A-number.

Some examples using the SMTP API:

Email addresses are limited in the characters they support. Our parsing is based on a subset of URL query strings. Supported characters are:

Formally, email addresses are bound by the RFC5322 standard (Wikipedia), which supports query strings. However, many devices have additional constraints, see below.

The RFC standard specifies

where an email address is [User]@[Domain]. There are, however, devices that set the total limit to 64 characters.

Due to lacking support in many cameras and other network equipment, we provide a fallback:

This means that the following two email recipient addresses are equivalent and will be parsed the same way:

folder=folder-1&[email protected]

[email protected]

The length limit can sometimes be a problem. We therefore support shorthands:

The recipient field takes one of two main formats

To select the right api, the api=[the-selected-api] parameter is used. The shorthand for api= is a=.

Four examples are given below

Emails are parsed using the generic API unless another is explicitly specified. This API gets all information from the email recipient (to) address or the query parameters to the HTTPS request.

The parameters that can be specified are:

When the camera name is specified it is recommended to also specify a site-unique folder to avoid two cameras getting the same incoming camera id.

Either incoming-camera-id or camera needs to be specified.

Will directly correlate the incoming alarm to the camera with the unique incoming camera id camera-841748

Uses the recommended folder + camera name structure to generate a unique incoming camera id.

The incoming camera id name will be site-abc_-_camera-123

The camera, when created in the system, will be called Camera 123 and placed in the folder Site ABC

Uses the recommended folder + camera name structure to generate a unique incoming camera id.

_-_ is used to separate two folder levels

The incoming camera id will be us-east_-_connies-construcion_-_camera-12

The camera, when created in the system, will be called Camera 12 and placed in the folder tree US EAST / Connies Construction

Equivalent to Example 3, but with shorthands and replacement characters to support more equipment and to get below 64 characters in length.

The above example will generate the unique incoming ID using only the camera name, meaning that when another Camera-14 is added to the system, the results will be unpredictable.

The hikvision-1 has been created to deal with the fact that many Hikvision NVRs and DVRs are unable to specify different Recipient (to) email addresses for different connected cameras. It uses the parameters specified by the user, as well as convention-based metadata set by Hikvision in alarm clip file names and the email body to generate a unique incoming camera id.

The supported parameters are