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 R-Service account. It is also possible for monitoring tools to use the Events API to register new requests.

Sending Email

Each R-Service account has its own email address. The email address of a R-Service account is example@mail.r-service.tech, where example is the id of the account. You can find the id of your organization’s R-Service account when you open the ‘Account Overview’ section in the Settings console.

In addition, each team that is registered in a R-Service account can be given its own email address. An email address of a team looks like team-name.example@mail.r-service.tech, 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, R-Service 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 R-Service email addresses.

It is important to verify that the Email Policy option ‘Allow inbound email to generate new requests’ is checked. If it is not, an inbound email message will not cause a new request to be generated and the sender of an email will receive an email that is based on the email template ‘Email Rejected’.

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 a R-Service account or one of its teams, the email is checked first to ensure that the sender is allowed to register new requests in this R-Service 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 R-Service 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 Policy 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 R-Service. 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 a R-Service account, then it can include parameters in the email it sends to the email address of this R-Service 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 a R-Service account and this Person record needs to have the Specialist role in the account which email address is example@mail.r-service.tech. If this person does not have the Specialist role of this account, the parameters are ignored.

Overriding the From email address

When the Email Policy option ‘Allow email parameter #from’ is set, you can override the From email address by adding the header fields X-4me-From and X-4me-Auth. This allows the creation of a request on behalf of someone else.

For example this email will create a request on behalf of beatrice.baldwin@example.com:

From: demo-request-webform@example.com
X-4me-From: beatrice.baldwin@example.com
X-4me-Auth: SECRET
To: example@mail.r-service.tech,
Subject: Request for product demo

I would like to request a demo of your product.

To be accepted, the value for X-4me-Auth must match a configured value in the Email Policy and the email must pass the DMARC policy of the sending domain.

Attachments

When an email contains one or more attachments, these files are automatically attached below the note that the Mail API adds. The number of attachments that can be added by the Mail API from an inbound email is limited to 20.

Inline images that are included in the body of the email get added as inline images in the note that the Mail API adds.

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 workflow template, then the Member field of the request is set to the manager of the workflow.
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.
sourceID
Set to the Message-ID value from the raw source of the email. (for example: 2142703314.3093062.1604928617247@mail.yahoo.com).
status
Set to assigned. When the template_id parameter is used and the request template is linked to a workflow template, then set to workflow_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. Make sure you include a blank line between the parameters and the text of the email body.

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.
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 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.
markdown
Used to indicate that the contents of the email body uses Text Formatting.
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 ID.
problem_id
Used to specify the problem that is to be related to the request. The problem needs to be identified by its 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 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 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.
sourceID
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 ID.
supplier_requestID
Used to specify the identifier under which the request has been registered at the supplier organization.
support_domain
Used to specify the support domain in which the request is to be registered. The support domain needs to be identified by its ID. The ID of a R-Service account can be found in the ‘Account Overview’ section of the Settings console.
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 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 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.
time_spent
Used to specify the time spent working on the request, in minutes.
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.
workflow_id
Used to specify the workflow that is to be related to the request. The workflow needs to be identified by its ID.

Custom fields

It is possible to assign values to custom fields that are defined in UI extensions. Each custom field and its value is defined on a line of its own. The parameter name is the ID of the custom field with custom_field_ preprended. For example:

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 R-Service 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.

Adding a note to an existing record

When an email is received the content may be added as a note to an existing record. This requires that the option ‘Allow replies to be added as notes’ is checked in the Email Policy of the receiving R-Service account, and the record to which a note is added is allowed to be accessed by the sender, and the record:

The value of <x> can be configured by account administrators via the Provide feedback field on the Self Service Settings form. It is set to 28 days by default.

If not all of these conditions are met, the Mail API opens a new request with a note containing the body of the reply.

If all of the above conditions are met, the following matching options exist:

Replies to automatic notifications

R-Service 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, workflow, task, project or project task for which the original email was generated.

Replies to email threads

If an email was send to multiple people where the inbound mailbox address was mentioned in the To: or Cc: field of the email then a new request is created in R-Service. If someone replies to such an email then R-Service will recognize this to be part of an email thread, and will add the content as a note to the previously created request.

For this to work email clients are expected to conform to the email standard RFC5322, and specifically include correct In-Reply-To and References email headers.

Based on Source and SourceID

It is also possible to update an existing request, problem, release, workflow, workflow task, project or project task by sending a new email to the email address of a R-Service account (i.e. this email does not need to be a reply to an automatically generated email message from R-Service or part of a previous email thread). To do this,

The rules that are applied to each inbound email are:

If no match was made it tries to match based on an ID in the subject field next.

The value of <x> can be configured by account administrators via the Provide feedback field on the Self Service Settings form.

Based on ID in subject

It is also possible to update an existing request, problem, release, workflow, workflow task, project or project task by sending a new email to the email address of a R-Service account (i.e. this email does not need to be a reply to an automatically generated email message from R-Service or part of a previous email thread). To do this,

The rules that are applied to each inbound email are:

The value of <x> can be configured by account administrators via the Provide feedback field on the Self Service Settings form.

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 it has attachments, or when its text is different from a previous note of the existing request. If the note has no attachments and the body text is either blank or the same as a previous note, 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 prevent the generation of a new request when 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. In that case, no note will be added to the existing request, unless the email has attachments.