Integrator > Initiate a form by email

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>@<formID>.<company>.xmatters.com

  • <recipient>: The recipient ID can be the user ID of a specific user or the name of a group or dynamic team. For example: mmcbride@traveladvisory.acmeco.xmatters.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.

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: