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.
Form initiation email format
The email address that you use to initiate the form is created from the recipient's user ID, the form ID, and the company name 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. For example: email@example.com or OracleDatabaseAdministrators@italters.acmeco.xmatters.com.
- <formID>: By default, the form ID is the name of the target form without spaces and in lower case.
- <company>: The name of your company in xMatters, for example: acmeco.
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.
Sending an email to this address initiates the form to the specified recipients. To target more than one recipient with a single event, add multiple email address 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 who have subscribed to the form.
Be aware that even though spaces are allowed in email addresses, many popular email clients do not permit them. We recommend not using spaces in group or dynamic team names if they are to be targeted via inbound email.
The following 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 and the company name is acmeco.
In this example, the Subject and body fields of the email are mapped to the text fields, Summary and Further Instructions. When the event is initiated, Mary McBride and the All Employees group are sent a notification where 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.
For more information about mapping email fields to text properties, see Configure forms for email initiation.
You cannot initiate a form using a notification sent by xMatters. To create new events in xMatters based on responses or existing events, use the Integration Builder.
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.
Troubleshooting email form initiation
If you are having problems successfully initiating a form by email, try the following troubleshooting steps:
If you try to initiate a form that does not have email form initiation enabled, the form will not be initiated. You may get an email reply with a message similar to the following: "The Form with ID 'myform' is not configured to be initiated by email. Log on to xMatters and configure Email Initiation."
If you have administrative privileges, check the Web Service Audit Report. If email initiation is not enabled for your form, it logs a FORM_IS_NOT_ENABLED error.
To check if email initiation is enabled for your form:
- Locate the communication plan that contains the form you want to configure, and click Edit > Forms.
- Locate the form that you want to configure, and ensure that the Enable Email Initiation check box is enabled for the form.
Check the sender permissions of the form to confirm that you, or a role that you are assigned, have permission to send the form. If you can't initiate a form in the web user interface, you won't be able to initiate it over email.
Configuring the To: line correctly is very important. It tells xMatters which company and form to use, and who the targeted recipients are. You can find a sample email address to use in the xMatters web user interface.
If you have permission to sign in and view communication plans, navigate to the form, click the Form drop-down list, and select Set Up Email Initiation. The dialog window shows you a sample email address using your user ID that you can use to initiate the form and send a notification to yourself.
The sample email shows how to send yourself a notification. How do you send a notification to other users, groups, or dynamic teams?
- To send another user a notification, use their user ID before the @ symbol.
- To send to a group or dynamic team, use the group or team name before the @ symbol. (Spaces in the name of the group, or quotations, are not recommended.)
- To target multiple recipients, use multiple addresses on the To: line. The addresses must all refer to the same company and form.
What happens if you put email addresses for different forms in the same email?
The event for the first email address is initiated and the rest are ignored.
What happens if you use the Cc: or Bcc: lines instead of the To: line?
The Cc: and Bcc: fields are treated the same as the To: field. You can initiate events by including email addresses in the Cc: and Bcc: fields.
What happens if my email server changes the To: address when sending?
Some email servers have a feature called "CNAME expansion" enabled that can alter the "To:" address of an email to include routing information. So an email sent to
firstname.lastname@example.org might be changed during transit through your email server to something more like
To address this problem, you'll need to work with your IT team to disable the CNAME expansion feature or setting on your SMTP email server.
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.
For security reasons, form initiation emails are only accepted when they are sent from certain email addresses (i.e., email addresses that are assigned to an email device for a user who has permission to initiate the form). Emails sent from users who don't have the correct permissions, or from random spammer accounts, will be rejected.
To verify if the email address of the sender is considered valid by xMatters:
- On the Devices screen in the web user interface, confirm that the email address that you are sending the initiation email from matches the address for one of your email devices.
If you have administrative privileges, check the Web Service Audit Report logs. If the event initiation failed because there are no users with that email address that have permission to send the form, the report logs a NO_USER_WITH_FORM_PERMISSION error.
When you use email form initiation, values in the email fields (subject, plain text body, HTML body, and from) can be mapped to text properties of the form. For example, for a product recall message you could map the email's subject field to the form's Product Name text property and then set the product name by typing it as the subject of your email.
You can only map values from an email to a form's text properties. If a form property is required, it must be mapped to an email field that is set when the event is initiated.
What happens if you don't provide a value for a required field?
If you attempt to initiate a form that does not populate the value of a required field (such as by sending an email without a subject when the email subject maps to a required form property), the event will not be initiated. The Web Services Audit report logs an error with the return status MISSING_FORM_FIELD.
What happens if a form contains a non-text property field marked as required?
The web user interface does not allow you to enable email initiation for a form unless all of the form's required properties are mapped to email fields. If you want to initiate this form by email, you'll need to mark the property as not required, or use a text box to represent the information instead.
What happens if a form is enabled for email initiation, but a new required property is added to it?
When you mark a new property as required, email initiation is disabled until it is mapped to an email field. Map the property to an email field and then re-enable email form initiation.
What happens if the value you type into an email field is longer than the number of characters that the form allows?
The event is initiated and the message is truncated to fit the available length of the property.