Inbound email actions allow defining actions an instance takes when receiving an email. They allow to process inbound email as either an automatic reply or as a record in the system. The processing takes the type of incoming mail and other attributes into account.

They are similar to business-rules in the usage of scripts and conditions that perform actions on the target table. Emails are checked by inbound email actions for defined conditions and some watermark that associates the email with a task. If the conditions are met, then the inbound email action performs the pre-configured activities. They may be of two types:

  • Record Action: runs a specified script.
  • Reply Email: when triggered, sends a reply email.

For inbound email processing, the default email account must be configured preliminary. See Email processing to learn more about email accounts configuring.

Inbound email actions are most commonly used to process emails (for example, create a new incident when a received incoming email contains "Incident" in the subject line).

Configuring 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 changes.

Role required: admin.



FieldMandatoryDescription
NameNInbound action displayed name.
Action TypeN

The action type. Available options:

  • Reply Email
  • Record Action.

When the Reply Email option is chosen, then the action behavior is to send an email in reply when triggered.

When the Record Action option is chosen, then the script runs (it should be specified in the Script field).

Please note that the Reply Email inbound action uses a default email account for sending emails, even when more than one email account is available.


TypeN

The message type required to run the action. Available choice options:

  • New – newly created letters, neither reply nor forward.

  • Reply – letters with distinctive features such as the subject line beginning with a recognized prefix (optionally) or Reply-To email header included in message.

    Letter type is defined by the content of letter subject. Keywords for reply letters are defined in the simple.email.reply_subject_prefix property.


  • Forward – forward letters, in line with the reply letters, usually can be distinguished by watermarks, or subject lines, or any other features.

    Letter type is defined by the content of letter subject. Keywords for forward letters are defined in the simple.email.forward_subject_prefix property.


  • All – these category summarizes letters of all types (new and reply and forward letters).
DSNN

Select this checkbox to trigger the action in response to Delivery Status Notification letters.

This option is applied as long as selected inbound action Type is All.


InvitationN

Select this checkbox to trigger the action in response to Invitation letters.

This option is applied as long as selected inbound action Type is All.


DescriptionNEnter the detailed description of what this email action does (optionally).
Reply EmailNCompose the email message. It will be sent to the source address which triggered the inbound action.
FromY

Reference to the user, on behalf of which the script is executed, or the reply letter is sent.

ScriptN

Enter a script that will trigger the inbound email action. You can use all methods of server-side API classes here.

In the Inbound Action script, the email object is available. The object is the 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. For this, you need to use properties with names corresponding to the names of record fields. For example: 

const newTask = new SimpleRecord('task');
newTask.subject = email.subject;
newTask.subject = email.body_text;
if (email.blind_carbon_copy) {
    newTask.attention_required = true;
}
cosnt insertedTaskID = newTask.insert();



TableNSelect the table where the action adds or updates records.
ActiveN

Select this checkbox to activate the action.

OrderNEnter the number to define the order of action processing. Actions are processed in ascending order (lower numbers are processed first).

Stop Processing

NSelect this checkbox to terminate other inbound actions after the current action runs.


Use case

We need to configure an inbound action implementing the following logic:

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

We create an inbound action as below:

FieldValue
NameCreate incident (access issue)
Action TypeRecord Action
TypeNew
ActiveTrue
Script


(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 actions logging

Every inbound action triggering is logged in the Script Log table. These logs can be filtered using the criteria below:

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

The Essence Document field is responsible for email processed by inbound action. You can enter full address or a part of it, and you can use precision or imprecision condition operators, respectively.

Use the Condition Builder to build filters that fit your needs.

/


Related articles