Mail API
Integrations Events and Mail API Mail API

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 4me account. The Mail API can also be used to add a note to an existing request, problem, task, etc. by including the ID of the record in the Subject field.

The 4me Email Addresses

Each 4me account has its own email address. In the production environment the email address of a 4me account is account_id@mail.4me.com, in QA this becomes account_id@mail.4me.qa. You can find the id of your organization’s 4me account when you open the ‘Account Overview’ section in the Settings console.

The Mail API is available for each 4me demo instance. To tell the Mail API for which demo instance the inbound email is intended, the name of the demo instance needs to be included in the email address to which the email is sent. This is different from the QA and production environments of 4me where only the name of the 4me account needs to be included in the email address.

If the name of your demo instance is Instance1 and the 4me account in which you want to generate a new request is wdc, you can send the email to wdc+Instance1@mail.4me-demo.com

In addition, each team that is registered in a 4me account can be given its own email address. An email address of a team looks like team-name.account_id@mail.4me.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.

There's one other Mail API feature that is unique to the demo environment. This feature makes it possible to specify the email address of the person who is sending the email to the Mail API. In QA and production, the sender's email address is automatically picked up for this. In the demo environment it is possible to overwrite this using the #from: parameter.

The 4me Email Policy

It is important to verify that the Email Policy option ‘Allow inbound email to generate new requests’ is checked (see Settings console, option Email Policy). 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’.

The 4me Email Parameters

When a request is created by an email you can set some request fields by specifying a parameter at the start of the email body. A parameter should start with a hashtag # and between the parameters a new line must be set.

Note that:

For example with the following parameters in the email body the Requested for user, a Configuration Item, the Team and the Team Member are set to the new request :

#source: Nagios
#sourceID: 98899-9
#requested_for: jane.young@example.com
#ci: P31
#team: SAP Basis Support
#member: john.smith@example.com


email body …

Exercises

First use the Request Templates API to find the id of the ‘Move Widget Data Center desktop PC’ template:

curl -X GET -i -H "Authorization: Bearer <personal-token>" -H "X-4me-Account: wdc" "https://api.4me-demo.com/v1/request_templates?subject=Move%20Widget%20Data%20Center%20desktop%20PC&fields=id"

Then use the template ID to create the request:

First use the Configuration Items API to find the label of the ‘Expense Reporting Production Database’ CI in the ‘wdc’ account:

curl -X GET -i -H "Authorization: Bearer <personal-token>" -H "X-4me-Account: wdc" "https://api.4me-demo.com/v1/cis?name=Expense%20Reporting%20Production%20Database&fields=label&updated_at=>2010-01-05T23:00:00Z"

Then use the label of the configuration item to create the event:

Finish