Inbound Email Actions

Inbound email actions are most commonly used to process emails. For example, if an incoming email contains “Incident” in the subject line, the system creates an incident record.

Inbound email actions are similar to business rules in the usage of scripts and conditions that perform actions on the target table. Inbound email actions verify emails for defined conditions and features that associate an email with a task. If the conditions are met, the inbound email action performs the pre-configured activities. There are two types of them:

• Record action: runs a specified script.
• Reply email: sends a reply email.

Unlike Notification Rules, inbound email actions enable the user to interact with the records in the system.

For example, while processing an incident in the Information needed state, the system inserts the body of this email to the Discussion field in the Activity Feed when the caller sends their response. To do so, an inbound email action is created. The condition for this action is the presence of a certain text in the subject and the same task number as in the incident record.

caution

To process inbound email, set up the default email account. See the Email Accounts article to learn how to do it.

Email processing chain

The order in which an incoming email is processed is determined by the following parameters:

• A condition that an email should meet for the action to be executed.
• An action type to execute when an email is received.
• Parameters that control the processing flow.

The third group of parameters is required to organize multiple inbound email actions in a way that they check an incoming email to match the condition defined in each of them, in a certain order. One incoming email can trigger execution of none, one or several actions in a row, depending on the values of the Active, Order, and Stop processing when complete fields of the action.

Email integration procedure

Find below the basics of the email integration procedure:

1. The SimpleOne email client sends a request to the external email server.
2. The emails received in the response are saved in the SimpleOne database.
3. The system sends the emails to the Rabbit MQ for processing and further delivery to the SimpleOne instance, where they are processed again according to the configured business rules.

The email processing protocol:

1. The client requests emails from the server with 1 minute interval. The system requests the emails that have been received since 00:00 am of the previous day. The main features are:

   • The system adds only the emails that have not been added to the database before.
   • You cannot set the number of the emails that are collected within one request as it is not configurable.
   • All emails are stored in the INBOX folder.

2. The time limit for receiving the list of unprocessed emails within a task is one hour.

3. The email processing takes approximately 10 seconds.

4. An internal scheduler processes the emails by getting the list of email IDs according to the condition below: 'SINCE "' . date('d-M-Y', strtotime('-1 day')) . '"', where date('d-M-Y', strtotime('-1 day')) is the beginning of the previous day. You can filter the emails by date, but not by time.

The inbound email actions are processed starting from the action with the lowest Order, according to the following logic:

1. If the inbound email action is active (the Active checkbox is selected), the system starts checking the incoming email according to the action conditions.
   • If the action is not active, the system moves to the next one in Order.
2. The email is checked against the conditions of the action.
   • If the email does not match the conditions, the system skips the action and proceeds to check the next action from Step 1.
3. Depending on the value of the Action type field, a Script is executed, or a Reply email is sent.
4. The value of the Stop processing when complete checkbox is checked.
   • If the checkbox is selected, the rest of the actions down the chain are skipped, and the processing chain is terminated.
   • If the checkbox is not selected, the system proceeds to the next action and repeats Steps 1–4.
5. The email processing ends when the system completes all active actions or when an action is performed with the Stop processing when complete checkbox selected.

The email processing chain is shown in the diagram below:

Configure an inbound email action

1. Navigate to System Notification → Inbound Email Actions.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

tip

Role required: admin.

Inbound Email Action form fields

Field	Mandatory	Description
Name	N	Specify an action name.
Action type	N	Select the action type. Available options: Record action – when triggered, the Script runs. Reply email – when triggered, an email is sent to the address that initiated the action. Its content is determined by the Reply email field. The Reply email action uses the default email account for sending emails, even when more than one email account is available.
Message type	N	Specify a message type required to run the action. Available choice options: New – newly created emails, neither reply nor forward. Reply – emails with a subject that starts with one of the prefixes defined in the simple.email.reply_subject_prefix property. Forward – forward emails with a subject that begins with one of the prefixes defined in the simple.email.forward_subject_prefix property. All – emails of all types (new, reply and forward emails).
DSN	N	Select this checkbox to trigger the action in response to Delivery Status Notification emails.
Invitation	N	Select this checkbox to trigger the action in response to Invitation emails.
Description	N	Add a detailed description of what this email action does.
Reply email	N	Enter the text of the reply letter. It will be sent to the original email address that initiated the action.
From	Y	Select a user, who initiates a script execution, or sends a response email.
Script	N	Enter a script that is triggered by the inbound email action. You can use all methods of server-side API classes.
Active	N	Select this checkbox to activate the action.
Order	N	Enter a number to define the order of action processing. Actions are processed in ascending order.
Stop processing when complete	N	Select the checkbox to end the message processing after the current action is completed. All subsequent actions (with a higher Order) are ignored.

note

The following objects are available in a script:

• email is an instance of the SimpleRecord class and refers to a record from the Email (sys_email) table that the action will process. To get the values of the record fields, use the dot-notation for the email object. To do so, use properties with names corresponding to the names of record fields.
• event is an instance of an entry in the Inbound Email Action (sys_email_inbound_action) table.

Inbound Email Action script example

(function runAction(/*SimpleRecord*/ event, /*SimpleRecord*/ email) {
const newTask = new SimpleRecord('task');
newTask.subject = email.subject;
newTask.description = email.body_text;
if (email.blind_carbon_copy) {
    newTask.attention_required = true;
    }
cosnt insertedTaskID = newTask.insert();
}

Use case

---

You need to configure an inbound email action implementing the following logic:

• When the system receives an email with the subject containing the keyword “access”, a new incident is created and assigned to the group responsible for security and access to the system and data.

Create an inbound email action as shown below:

Field	Value
Name	Create incident (access issue)
Action type	Record action
Message type	New
Active	true
Script	Script example below.

Script example

(function runAction( /*SimpleRecord*/ event, /*SimpleRecord*/ email) {
 
    ss.importIncludeScript('EmailHelper');
    const helper = new EmailHelper();
 
    const letter = email.subject.match('aсcess'); // Keywords checking
    if (letter) {
        const incident = new SimpleRecord('itsm_incident');
        incident.subject = email.subject;
        /* If the sender's address is registered in the system,
        the Caller field will contain reference to an existing User record.
        If the address is unknown, the caller will be defined as Guest */
        incident.caller = helper.userIDbyEmail(helper.parseSender(email.from));
 
        incident.description = email.body_text;
        incident.state = '-2'; // Registered
        incident.contact_type = '20'; // Email
        incident.assignment_group = '162920380313692887'; // Security Group
        incident.impact = '2'; // Moderate
        incident.urgency = '2'; // Moderate
        const insertedIncidentId = incident.insert();
 
        if (insertedIncidentId != 0) {
            ss.debug(`Email ${email.sys_id} processing result: Incident with ID ${insertedIncidentId}`);
 
            const attach = new SimpleAttachment();
            attach.copy('sys_email', email.sys_id, 'itsm_incident', insertedIncidentId);
            return;
        }
        ss.error(`Inbound Action Failed!\nErrors:` + JSON.stringify(incident.getErrors(), null, 2));
    }
})(event, email);

Inbound email action logging

Every inbound email action triggering is logged in the Script Log. You can filter these logs using the criteria below:

• Source IS Inbound Action
• Essence document CONTAINS 0229fa8a-bcbe-1f11.

caution

The Essence document field is responsible for email processed by the inbound email action. Enter the full address or a part of it, and use precise or imprecise condition operators.

Recommendations

The incoming mail parsing returns the address value for the From field of a record from the Email (sys_email) table in lower case.

When searching for a user by email in the Script column, do not use the IS operator because the value of email can be entered with uppercase letters. For example, *J.Doe@mail.com*.

Not Recommended

user.get('email', 'j.doe@mail.com');

Also, do not use the LIKE operator when searching for a user by email because the search will find a user with a similar email, for example, 'raj.doe@mail.com'.

Not Recommended

user.get('email', 'like', 'j.doe@mail.com')

The following example shows the script with the userIDbyEmail() method that searches for a user by email value:

ss.importIncludeScript('EmailHelper');
class MyEmailHelper extends EmailHelper {
    userIDbyEmail(email) {
        const user = new SimpleRecord('user');
        user.addQuery('email', 'startswith', email);
        user.addQuery('email', 'endswith', email);
        user.selectAttributes('sys_id');
        user.setLimit(1);
        user.query();
        if (user.next()) {
            return user.sys_id;
        }
        return this.searchGuest();
    }
}