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.

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.

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.

Integrate with an external system

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.

xMatters accepts 9 and 10 character BATV-encoded email addresses.

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.