From this article you will learn:
- What is the Email Notifications extension
- What are the common use cases
- How to set up the Email Notification extension
- What are the available configuration parameters
What is the Email Notifications extension?
Email Notifications Extension can send email notifications at annotation status change which helps you keep track of new documents or undesired transitions such as failure to export the document.
Another possibility is a periodic evaluation email-sending trigger. You can use it as a reminder of forgotten documents waiting for your action. This function can send emails with fully customizable templates that allow placeholder values, such as links to the triggering documents.
Common use case configurations for Email Notifications extension
Below are setup examples you can copy and modify for easy setup.
Email notification on the successful export of a document
In this example, we want to get notified of any document successfully exported from queue 3. The function will send an email template 1 to the my_accounting_address@my_company.ai email address.
Example:
- Affected queue: 3
- Email template used: 1
- Email addresses notified: my_accounting_address@mycompany.ai, someone_else@mycompany.ai
- Event: document successfully exported
{
"actions": [
{
"scope": {
"type": "queue",
"filter": [
"3"
]
},
"trigger": {
"type": "status_change",
"status_to": "exported"
},
"template": 1,
"recipients": {
"type": "explicit",
"to": [
{
"name": "Accounting",
"email": "my_accounting_address@mycompany.ai"
}
],
"cc": [
{
"name": "Someone Else",
"email": "someone_else@mycompany.ai"
}
]
}
}
]
}
Periodic notification for documents waiting to review
In this example, the trigger is evaluated periodically on a given expression. We use an expression to filter documents that are in to_review status. Additionally next part of the expression filters emails that arrived in the last 30 days. You may define multiple conditions with the & operator in the scope object. There is also the definition of threshold, which sets the minimum number of documents for triggering a notification to 20.
Example:
- Affected queue: 4
- Email template used: 2
- Notification threshold: 20
- Email address notified: All email addresses assigned to the queue
- Evaluated expression: status=to_review&arrived_at_before={date.today() + timedelta(days=30)}&arrived_at_after={date.today() – timedelta(days=30)}
- Recipients: emails associated with the queue
{
"actions": [
{
"recipients": {
"type": "queue"
},
"trigger": {
"type": "expression",
"filter": "status=to_review&arrived_at_before={date.today() + timedelta(days=30)}&arrived_at_after={date.today() - timedelta(days=30)}",
},
"scope": {
"type": "queue",
"threshold": 20,
"filter": [
"4"
],
},
"template": 2
}
]
}
How to set up the Email Notification extension
Setting up the extension itself takes a few simple steps.
Step 1: Prepare your queues and email templates
The first step is to identify the queue(s) with the documents that require this function.
Then you need to create email templates:
- Click Queue Configuration > Emails > Smart email automation > Create a new template.
- Define the Name, Subject, and Message of the email.
- Click Save.

The email template may contain placeholder parameters. In addition to the built-in template placeholders, you can also use additional values that are available only for this extension:
{{document_urls}}
: an unformatted list of document URLs that correspond to the action filters.
{{document_count}}
: the total count of documents that have been matched by the action filters.
{{queue_url}}
: the URL of the outgoing queue.
{{queue_name}}
: the name of the outgoing queue.
{{current_timestamp}}
: the current timestamp, provided in the format “%Y-%m-%d %H:%M:%S”.
- Get the ID of the template you have just created from the edit template view:

Step 2: Activate Email Notifications in the Rossum Store
To enable Email Notifications, go to the Rossum application and:
- Click on the Extensions tab at the top of the app
- Click on the Rossum store option to display all the available extensions
- Select the “Email Notifications” extension tile
- Click “Try extension”

Step 3: Specify to which queue(s) you want to add this extension.
In the “Rossum Store Extension Settings,” scroll down to “Queues” and select the queue(s) in which you want to use the function. Please remember to save your changes once you’ve chosen the desired queues.
Step 4: Set up email notifications
You can set up the Email Notification function using the configuration field in the UI or the settings attribute of the hook API object. First, you need to set up trigger events. Relevant events are:
- Document status - Changed : triggered whenever a document changes status
- Invocation - Scheduled : periodically evaluated for relevant documents

Next, go to the configuration. It is in JSON format. It consists of a list of actions that should be evaluated to trigger the email. Additionally, the function requires access to Rossum API, so set yourself up as a token owner.

Complete list of available parameters:
* All schema IDs used on the expression (except for params on the timedelta Object) must be of type date (Rossum schema field type). If a metadata field is used in the expression, the extension will parse only its date part and use it for the calculation.
Attribute | Type | Required | Parent | Description |
actions | list | yes | – | List action definitions containing recipients , trigger , scope , and template . |
recipients | list | yes | action | List of an object defining recipients to be notified. Contains type and values . |
type | string | yes | recipient | Possible values are queue , which uses all email addresses associated with the queue, or explicit . |
to | list | yes (only for the explicit type) | recipient | List of “to” recipient objects. They have two keys: name and email . |
cc | list | no (only for the explicit type) | recipient | List of “cc” recipient objects. They have two keys: name and email . |
bcc | list | no (only for the explicit type) | recipient | List of “bcc” recipient objects. They have two keys: name and email . |
name | string | yes | to/cc/bcc | Display the name of the email recipient. |
string | yes | to/cc/bcc | Email address | |
trigger | object | yes | action | Trigger object containing type and params . |
type | string | yes | trigger | Possible values are status_change , for document status change events or expression , for the scheduled ones. |
status_from | string | no | trigger | Defined in annotation lifecycle for matching of the initial status. |
status_to | string | no | trigger | Defined in annotation lifecycle for matching of the new status. |
expression | string | no | trigger | Evaluated on fetched annotations.* |
filter | string | no | trigger | Query filter to limit fetched annotations. Applied in Elis API. |
scope | object | yes | action | Evaluation scope. Contains type , threshold , filter , and outgoing_queue . |
type | string | yes | scope | Type of scope. Possible values are document or queue . |
threshold | int | no | scope | A minimal number of positively matched documents to send notification. |
filter | list | no | scope | List of strings of filtered queue ids or document ids. Depends on the scope type. |
outgoing_queue | string | no | scope | The ID of the outgoing email queue. |
template | int | yes | action | The ID of the email template created in Rossum. |
It is possible to define the parameter of the timedelta object using the schema_id. The user can decide to use an integer value. If you use an incompatible value, the function will fail.
The expression supports the use of the today() method to get the current date.
If you encounter any problems, contact us at support@rossum.ai.