Mail API

The Mail API can be used by end users and monitoring tools to submit requests by sending email to the email address of a service provider organization’s ITRP account. It is also possible for monitoring tools to use the Events API to register new requests.

Sending Email

Each ITRP account has its own email address. The email address of an ITRP account is example@itrp.com, where example is the id of the account. You can find the id of your organization’s ITRP account when you open the ‘Account Overview’ section in the Settings console.

In addition, each team that is registered in an ITRP account can be given its own email address. An email address of a team looks like team-name.example@itrp.com, where team-name is the local part of the email address that is unique for the account. This local part can be defined by an administrator of the account.

When an email is sent to the email address of the account or one of its teams, ITRP uses the information of this email to generate a new request. If it was sent to a team’s email address, the new request gets assigned to that team.

Another email address (e.g. one within your organization’s internet domain) can be made available for each of these inbound email addresses. These email addresses can then be used by end users and system management tools to send their email to. Filters can then be applied in these mail accounts before they forward email to their corresponding ITRP email addresses.

Note, however, that it is not possible to send email to a directory account. That is because requests cannot be stored in a directory account. When a directory account is used, email needs to be addressed to one of its support domain accounts, or a team that is registered in one of these support domain accounts.

Mail from end users

After an email has been received at the inbound email address of an ITRP account or one of its teams, the email is checked first to ensure that the sender is allowed to register new requests in this ITRP account. If a Person record exists in this account, or in its directory account, with an email address that matches the address of the sender, then the information of the email is used to generate a new request.

Note that the Mail API first looks for a match with the primary email address of a person. If a match cannot be found with a primary email address, then the Mail API continues to look for a match by going through the other email addresses that are specified in the Person records of the account, or its directory account.

It is possible to configure ITRP to automatically create a new Person record when an email is received from an address that does not match an email address of any of the existing Person records within the account, or its directory account. This can be done in the Email Policies section of the Settings console.

The new request gets the following values:

Mail from monitoring tools

To allow a system management or monitoring tool to use the Mail API, a Person record needs to be registered for it in ITRP. This Person record needs to have an email address (preferably the primary email address) that matches the From email address of the email that the monitoring tool generates.

If the monitoring tool’s Person record has the Specialist role of an ITRP account, then it can include parameters in the email it sends to the email address of this ITRP account. Parameters are used to set field values in the new request.

Parameters need to be specified at the start of an email’s body. An example of an email with parameters is provided below:

Keep in mind that, in order for this example to work, a Person record with the email address nnm@example.com needs to exist in an ITRP account and this Person record needs to have the Specialist role in the account which email address is example@itrp.com. If this person does not have the Specialist role of this account, the parameters are ignored.

Attachments

When an email contains one or more attachments, then these files are automatically attached to the new request that the Mail API generates. Inline images that are included in the body of the email also get added as attachments to the new request.

Default values

To simplify the creation of new requests by monitoring tools, default values are used when parameters have not been provided for request fields that are required.

category
Set to incident if a service instance is to be related to the request. Otherwise, set to other.
created_by
Set to the sender of the email (Mail API does not allow any other value).
requested_by
Set to the sender of the email (Mail API does not allow any other value).
requested_for
Set to the sender of the email.
impact
Set to top if category is incident. Otherwise the Impact field of the request is left empty.
member
Set to the sender of the email if a valid member is not provided and a status is specified that causes the Member field of the request to be required. When the template_id parameter is used and the request template is linked to a change template, then the Member field of the request is set to the manager of the change.
service_instance
Set to the first service instance of the configuration item when a configuration item is specified for the request.
source
Set to email.
source_id
Set to the unique ID of the email.
status
Set to assigned. When the template_id parameter is used and the request template is linked to a change template, then set to change_pending.
team
The team to which the person specified as the member belongs. Otherwise, if a service instance is to be related to the request, the First Line Team of this service instance or, if a First Line Team is not specified or the sender of the email is a member of the First Line Team or the Support Team, the Support Team of this service instance. Else, set to the Service Desk Team of the first line support agreement that covers the account of the person selected in the Requested for field.
Note: if an invalid team was specified in the email, the default team is selected in the request.

Relying on all default values makes it possible to create a request by providing only a subject in the email.

Parameters

The following parameters are accepted to set the field values of a new request. Note that parameters cannot be used to update the field values of an existing request.

category
Used to specify an option in the Category field of the request. The available field options can be found in the Fields section of the Requests API page. Shortcuts are supported for this parameter. For example, #category: rfc is the same as #rfc.
change_id
Used to specify the change that is to be related to the request. The change needs to be identified by its ITRP ID.
ci
Used to specify the configuration item that is to be related to the request. The configuration item needs to be identified by its label or, in case of a software CI, its Name field value.
ci_id
Used to specify the configuration item that is to be related to the request. The configuration item needs to be identified by its ITRP ID.
ci_source
Used together with the ci_sourceID parameter to specify the configuration item that is to be related to the request. This parameter should be used to specify the configuration item’s Source field value.
ci_sourceID
Used together with the optional ci_source parameter to specify the configuration item that is to be related to the request. The configuration item needs to be defined using its Source ID field value.
completion_reason
Used to specify an option in the Completion reason field of the request when its Status field is set to completed. The available field options can be found in the Fields section of the Requests API page. Shortcuts are supported for this parameter. For example, #completion_reason: workaround is the same as #workaround.
desired_completion_at
Used to specify the date and time that has been agreed on for the completion of the request. The desired completion overwrites the automatically calculated resolution target of any affected SLA that is related to the request when the desired completion is later than the affected SLA’s resolution target. By default, the requested_by receives a notification based on the ‘Desired Completion Set for Request’ email template whenever the desired_completion_at is set, updated or removed.
downtime_end_at
Used to specify the end date and time of a service outage. Be sure to use the correct datetime format.
downtime_start_at
Used to specify the start date and time of a service outage. Be sure to use the correct datetime format.
impact
Used to specify an option in the Impact field of the request. The available field options can be found in the Fields section of the Requests API page. Shortcuts are supported for this parameter. For example, #impact: high is the same as #high.
internal
Used to indicate that the contents of the email body is to be added to the request as an Internal Note.
member
Used to specify the person to which the request is to be assigned. This person needs to be identified by the Person record’s Primary email field value.
member_id
Used to specify the person to which the request is to be assigned. This person needs to be identified by the Person record’s ITRP ID.
problem_id
Used to specify the problem that is to be related to the request. The problem needs to be identified by its ITRP ID.
requested_for
Used to specify the person who is to be selected in the Requested for field of the request. This person needs to be identified by the Person record’s Primary email field value. The requested_for parameter is processed only if the sender’s Person record has the Service Desk Analyst role.
requested_for_id
Used to specify the person who is to be selected in the Requested for field of the request. This person needs to be identified by the Person record’s ITRP ID. The requested_for_id parameter is processed only if the sender’s Person record has the Service Desk Analyst role.
service_instance
Used to specify the service instance that is to be related to the request. The service instance needs to be identified by its Name field value.
service_instance_id
Used to specify the service instance that is to be related to the request. The service instance needs to be identified by its ITRP ID.
source
Used to specify the name of the monitoring tool, see source. After the request has been created, this value is visible in its Audit Trail.
source_id
Used to specify the unique ID of the event for which the request is to be registered, see source. After the request has been created, this value is visible in its Audit Trail.
status
Used to specify an option in the Status field of the request. The available field options can be found in the Fields section of the Requests API page. Shortcuts are supported for this parameter. For example, #status: completed is the same as #completed.
supplier
Used to specify the Organization to which the request has been submitted. The Organization needs to be identified by its Name field value.
supplier_id
Used to specify the Organization to which the request has been submitted. The Organization needs to be identified by its ITRP ID.
supplier_requestID
Used to specify the identifier under which the request has been registered at the supplier organization.
team
Used to specify the team to which the request is to be assigned. The team needs to be identified by its Name field value.
team_id
Used to specify the team to which the request is to be assigned. The team needs to be identified by its ITRP ID.
template_id
Used to specify the request template that is to be applied to the request. This request template needs to be identified by its ITRP ID. It is important to note that the field values defined by the parameters in an email, including the text in the subject and body of the email, overwrite the values specified in the request template.
waiting_until
Used to specify the date and time at which the status of the request is to be updated from waiting_for to assigned. Be sure to use the correct datetime format.

Text formatting

It is possible to include basic formatting in the text of the email body below the parameters. The available formatting options are described in the Text Formatting section. To make sure that the formatting is applied in the new note of the request, the markdown parameter needs to be included in the list of parameters at the top of the email body.

Linking records of other accounts

If the Person record of the sender has the Specialist role of more than one ITRP account, then it is important to make sure that the records that are to be linked to the new request are obtained from the correct account. In such cases it is important to uniquely identify each record specified in the parameters by adding the id of the record’s account.

This can be done as follows:

In this example, the sender’s Person record must have the Service Desk Analyst role of the example account, because the requested_for parameter is used to submit the request on behalf of someone from the example account. In addition, the sender’s Person record must have the Specialist role of the other_account account to be able to link the configuration item, team and member records of the other_account account to the new request.

Replies to automatic notifications

ITRP sends out automatically generated email messages to notify people when specific conditions have been met. When a recipient replies to such a notification, the Mail API adds the reply as a Note to the request, problem, release, change, task, project or project task for which the original email was generated.

Adding a note to an existing record

It is also possible to update an existing request, problem, release, change, change task, project or project task by sending a new email to the email address of an ITRP account (i.e. this email does not need to be a reply to an automatically generated email message from ITRP). To do this, the ID of the existing request, problem, release, change, task, project or project task needs to be included in the Subject field of the email.

The rules that are applied to each inbound email that does not contain a reference to a request, problem, release, change, task, project or project task in the In-Reply-To or References fields (i.e. which is not a reply to an automatic notification) are:

Event matching

If an email is received within 24 hours of the creation of an existing open request that has the same account, source, requested_for, service_instance, and ci parameters, then a new request does not get generated. Instead, the body text (below the parameters) of the email is used to add a new note to the existing request. To avoid duplicate notes, however, the note is only added when its text is different from a previous note of the existing request. If the body text is the same as a previous note, or if there is no body text, then no changes are made to the existing request.

When the service_instance parameter is not included in the email, it is found by looking up the service instance to which the configuration item is linked. Once the service instance is known, the event matching starts.

When the ci parameter is not included in the email, event matching will not prevent the generation of a new request unless the subject and note parameters, as well as the account, source, and requested_for parameters are the same as those of an existing open request that was generated within the past 24 hours.