Initiate a form by email
You can initiate an event by sending an email to xMatters. When xMatters receives a form initiation email from a valid sender, it initiates the corresponding event and uses values provided by the email to set text properties of the event. The email address and mapping information is defined with the form in the communication plan builder.
You can set the values of text properties using email form initiation. However, other form properties, such as lists, hierarchies, numbers, etc. cannot be set using email form initiation.
For email form initiation to be successful, the following conditions must be met:
- The email form initiation feature is enabled for your company, and the form is configured to allow email initiation.
- The form name is unique within your company (not just unique within the communication plan).
- The form maps email fields to all required text properties. Form initiation fails if there are required properties that are not assigned a value.
- The initiation email is sent from a valid email address. Email addresses are valid when a user with permission to initiate the form has the email address configured as an email device.
- The initiation email can use multiple addresses to target multiple recipients, but the addresses must specify the same form.
- You have not exceeded the rate limit for the number of email form initiation requests. Requests that exceed the rate limit are not delivered to xMatters.
To learn more about the rate limit or to enable the email form initiation feature, contact your xMatters representative.
The email address that you use to initiate the form is created from the recipient's user ID, the form ID, the company name, and the address of your xMatters deployment in the following syntax:
- <recipient>: The recipient ID can be the user ID of a specific user, or the name of a group or dynamic team. Group and dynamic team names that contain spaces must be enclosed in double quotes.
- <formID>: By default, the form ID is the name of the target form without spaces and in lower case. To locate or modify the identifier of a form, seeConfigure forms for email initiation.
- <company> and <instance>: This should be the name of your company in xMatters, and the xMatters instance on which your deployment is configured; you can see both of these values in the URL you use to access the xMatters web user interface. For example, if you access xMatters at https://acmeco.na1.xmatters.com, then "acmeco" is your company and "na1" is your instance.
Group names that contain spaces must be enclosed in double quotes, for example "Oracle Database Administrators"@italerts.acmeo.na1.xmatters.com . Be aware that even though spaces are allowed in email addresses, some popular email clients do not permit them. If your email client does not allow you to use spaces in email addresses, use another email client to send the initiation email or rename your group.
You can find the form ID and sample email address on the Set Up Email Initiation page of the form in the communication plan builder. If you do not have permission to access this page, contact the form designer for this information.
To target more than one recipient with a single event, add multiple email addresses to the To: line of the email. These email addresses must refer to the same form.
Some users may be notified of the event even if you do not include them on the To: line. These include users that are pre-configured to be form recipients or users who have subscribed to the form.
This example shows how to address an email to initiate a tornado alert that targets the user Mary McBride, whose user ID is mmcbride, and the group All Employees. The form ID is tornadoalerts, the company name is acmeco, and the xMatters system is located at na1.xmatters.com:
When you initiate a form by email, you can use the subject and body fields of the email message to set the values of text properties in the form. When xMatters receives the form initiation email, it maps the values of the email subject and body fields to the form's text properties according to the field mapping configured for the form. For more information about configuring the field mapping, see Configure forms for email initiation.
Some forms have required properties that must be set before the form can be initiated. If a form has required text properties, they must be mapped to an email field and the field must be assigned a value when the form is initiated. Forms that contain other required properties (non-text) cannot be initiated by email unless they have been assigned a default value.
For example, consider a form that has two text properties, Summary and Further Instructions. You could map the subject of the email to the Summary property and map the plain text body of the email to the Further Instructions property. When you send the form initiation email, you then set the subject and body of the message as shown below:
When the event is initiated, the Summary field is set to Take cover now, and the Further Instructions field is set to Go to the nearest available shelter and take cover until the storm has passed.
You can map the following email fields to form properties:
- Subject: The subject of the email message.
- From: The sender of the email message.
- Body (Text): The content of the email message that is sent as plain text.
- Body (HTML): The content of the email that is sent as HTML
If a form has a required property, it must be mapped to one of the email fields. You must also ensure that the length of the text in the email field does not exceed the maximum length of the mapped form property.
Most email programs create either a plain text message body or an HTML message body. If the plain text body or HTML body field is mapped to a form value, ensure that your email program sends the message in the matching format. Some email programs may be able to send messages with both plain text and HTML content enabled.
For the form initiation email to be accepted, it must be sent from an email address that belongs to a user who has permission to initiate the event. For example, if Kelly Clarke has home and work email devices configured, she can initiate the event by sending an email from her home or work email account (assuming she has permission to initiate the event). She would not be able to initiate the event from another email address that is not assigned to a device in xMatters.
xMatters accepts email sent from BATV-style email addresses.
Email form initiation provides you with a powerful way to generate xMatters events from any system that is capable of sending an email. You can use this feature to initiate xMatters events automatically from your custom application or almost any cloud-based application, monitoring system, social media platform, e-commerce platform, or customer relationship management tool.
The email address that your external system uses to send requests must be recognized by xMatters. Otherwise, the request will be rejected. To enable xMatters to recognize emails from your external system, complete one of the following tasks:
- Add the external system email address as a device for a user that is already authorized to initiate the form.
- Create a new user in xMatters to represent the external system. Give this user permission to initiate the form, and create a device for the external system email address.
- Use a service that can receive an email message from your external system and resend it using a email address that is authorized to initiate the form.
If your system does not have the ability to send email messages, check out services like Zapier, which can be used to send email messages from a wide range of popular applications.