Flow triggers
A trigger is the mechanism for kicking off a flow in xMatters. Flow Designer includes different types of triggers, which are initiated either when event activities occur (such as an event status change, a specific response, or an added comment), or when information is injected into xMatters by an incoming HTTP request or email. Each trigger populates outputs based on the type of trigger, which are available to downstream steps in a flow. They can be easily identified in Flow Designer canvases by their circular icon.
Triggers only fire if there are steps connected to them (the exception is any legacy Integration Builder triggers, which continue to execute the scripts associated with them).
If you have existing outbound integrations for a form, they'll appear as triggers on the canvas. You can connect additional steps to these triggers to extend the current functionality of your outbound integrations.
The maximum number of requests you can submit within a one-minute period to xMatters is limited by your pricing plan. If you exceed this limit, your request will be rejected with a 429 error and will not be queued for processing.
Flow triggers
Event activity triggers
Event activity triggers kick off flows based on different event lifecycle activities, including event status updates, device delivery updates, responses, event comments, escalations, and targeted recipient failures. Each of these different triggers include a common set of event properties, and additional properties specific to the type of event activity.
Common properties
The common properties output by all event activity triggers provide information identifying the event in addition to its status and properties.

Common trigger output details
Property | Description | Example |
event.id | The unique identifier (UUID) of the event. | e930e32d-b863-4c55-a528-1d2829e3690e |
event.eventId | ID assigned to this event by xMatters and used to track its progress through the system. (Also the number used to reference this event in the Events and Tracking reports.) | 889003 |
event.status | The current status of the event. | ACTIVE |
event.created | Date and time the event was created in xMatters in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
event.priority | The priority assigned to the notification in xMatters (LOW, MEDIUM, or HIGH). | HIGH |
event.targetedRecipients | The recipients targeted for notification. |
bjones mmcbride|Work Email CustomerCare |
event.initiator | The target name of the user who initiated the event. | integrationUser |
event.properties | A JavaScript object containing the property names and values included in the event. |
|
Event status updates trigger
The Event Status Updates trigger initiates a flow when an event is started, suspended, resumed, or terminated. Outputs include the status of the event and the user who initiated the event status change.

Examples of when to use this trigger:
- Automatically update the record in your monitoring tool to add an annotation that the xMatters event ended.
- Post event creation and termination updates to your reporting repository for analytics and observability initiatives.
- Automatically close the ticket in the source system when the xMatters event ends.
Event status trigger outputs
Property | Description | Example |
statusChanged.auditType | The change to the event status that triggered the flow. Can be one of: EVENT_ANNOTATED, EVENT_COMPLETED, EVENT_CREATED, EVENT_RESUMED, EVENT_SUSPENDED, or EVENT_TERMINATED | EVENT_TERMINATED |
statusChanged.at | Date and time the event status changed in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
statusChanged.by.id | The unique identifier (UUID) of the user who initiated the event or changed the event status, or null if it happened automatically (for example, by timeout). | e1e427bb-770f-4d47-aa4d-efdd8b64089c |
statusChanged.by.targetName | The username of the user who initiated the event or changed the event status. | mmcbride |
statusChanged.by.firstName | First name of the user who initiated the event or changed the event status. | Mary |
statusChanged.by.lastName | Last name of the user who initiated the event or changed the event status. | McBride |
To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.
Device delivery updates trigger
The Device Delivery Updates trigger initiates a flow when a notification is delivered to a device, or when notification delivery fails. Outputs include the user and device that the message was sent to and whether the delivery was successful.

Examples of when to use this trigger:
- Post details about who was notified and when into a ticket, alert or chat application so the notification process is clearly visible (and documented).
- Post details about device notification failures to a list so you can follow up with users who seem to be experiencing delivery issues.
Device delivery trigger outputs
Property | Description | Example |
notification.deliveryStatus | The delivery status: Delivered, Failed, or Unchanged. | Delivered |
notification.recipient.id | The unique identifier (UUID) of the device the notification was sent to. | f51d0fa3-6712-4b4e-9da4- b8a631f8b8c1 |
notification.recipient.name | The name of the device the notification was sent to. | Work Email |
notification.recipient.targetName | The target name of the device the notification was sent to. | mmbride | Work Email |
notification.recipient.owner.id | Unique identifier (UUID) of the targeted user. | e1e427bb-770f-4d47-aa4d- efdd8b64089c |
notification.recipient.owner.firstName | First name of the targeted user. | Mary |
notification.recipient.owner.lastName | Last name of the targeted user. | McBride |
notification.recipient.owner.targetName | Username of the device's owner. | mmcbride |
deliveryStatusUpdated.at | Date and time the delivery status was updated in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
deliveryStatusUpdated.auditType | The general category of the device delivery attempt that triggered the flow. Can be one of: NOTIFICATION_DELIVERED, NOTIFICATION_ESCALATED, NOTIFICATION_FAILED, NOTIFICATION_NO_RECIPIENT, or NOTIFICATION_UNCHANGED | NOTIFICATION_DELIVERED |
deliveryStatusUpdated.delivery StatusType |
The detailed result or status of the delivery attempt that triggered the flow. A detailed list of delivery status types is available. | LIVE_NOTIFICATION_ PROVIDER_DELIVERED |
deliveryStatusUpdated.delivery StatusMessage |
A description of the result of the delivery attempt, which may include error codes. | Notification delivered |
To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.
Responses trigger
The Responses trigger initiates a flow when a user responds to a message. Outputs include the user and device that made the response, their response choice, and comments added from the mobile app.

Examples of when to use this trigger:
- Automatically assign an incident when a recipient responds with Accept (or Assign to me or whatever response you have configure for this).
- Approve or reject change requests based on responses.
Responses trigger outputs
Property | Description | Example |
response.response | The response the recipient selected. | Assign to me |
response.deviceName | Name of the device the recipient used when responding to the notification. | Android Phone |
respondedTo.at | Date and time the recipient responded to the notification in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
respondedTo.by.targetName | Username of the person who responded. | asamara |
respondedTo.by.id | The unique identifier (UUID) of the recipient who responded to the notification. | 871d855c-1cce-45a2-97e7-f185f51ed753 |
respondedTo.by.firstName | First name of the person who responded. | Ali |
respondedTo.by.lastName | Last name of the person who responded. | Samara |
respondedTo.auditType | The system action that triggered the flow (RESPONSE_RECEIVED) | RESPONSE_RECEIVED |
To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

To use the responses trigger, you need the individual responses that you want to trigger flows. If responses are already configured on the form, they appear under the parent trigger when you drop it on the canvas. If there are no responses, you can add them right from within Flow Designer.
- Click Add Response (or double-click the Responses parent) to add, remove, or edit response options.
- Configure the response options, drag them into the order you want them to appear on the canvas, then click Save. In our MIM scenario, we added "Create major incident" and moved it to the top of the list.
Each response appears as a step on the canvas. You can now connect the steps you want to run when a recipient selects that response.
A few things to know about existing integrations:
- If you have an outbound integration that uses the Notification Responses trigger, it appears on the canvas but doesn't have the response options delineated since any actions based on different responses are handled in the outbound integration script.
- Some integrations use response options that are determined at runtime. We've updated our built-in integrations but some packaged or custom integrations still use these. For the time being, you'll need to continue to use an outbound integration using the Notification Responses trigger.
- For built-in integrations, you are unable to modify or delete the default response options included in the configuration; although you can add additional ones. To modify or delete built-in responses, you'll need to first convert the configuration to a workflow.
Event comments trigger
The Event Comments trigger initiates a flow when a user adds a comment from the mobile app, xMatters Inbox, email, Tracking Report, or xMatters REST API. Outputs include the user that made the comment and the content of their comment.

Examples of when to use this trigger:
- Post each comment to a Slack channel or other chatops application.
- Populate the free-form text closure details of a ticket or alert (in this case, you could actually perform your response logic in the Event Comment trigger instead of the response trigger!)
- Add the comments to a ticket or alert as annotations, recording the work performed on the event, either for the next person in the resolution chain or for post-incident analysis.
Event comments trigger output details
Property | Description | Example |
annotation.comment | The value of the comment added to the event by the user. | Investigating the root cause now |
annotated.at | Date and time the comment was added in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
annotation.author.targetName | The username of the user who added the comment. | asamara |
annotation.author.id | The unique identifier (UUID) of the user who added a comment to the event. | 871d855c-1cce-45a2-97e7-f185f51ed753 |
annotation.author.firstName | First name of the user who added the comment. | Ali |
annotation.author.lastName | Last name of the user who added the comment. | Samara |
annotation.response.response | The response the user selected when they added a comment, or null if they commented without selecting a response. | Assign to me |
To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.
Escalations trigger
The Escalations trigger initiates a flow when an escalation occurs in a group. Outputs include the group containing the shift with the escalation, the reason for the escalation, the user that escalated the event (if it was escalated manually), the type of escalation, the recipients the event escalated from, and the recipients the event escalated to.

Examples of when to use this trigger:
- Automatically launch a new event that warns a manager when an event has escalated to the point where an SLA (service level agreement) is in jeopardy.
- Automatically update a chat room to warn team members when an event is escalated.
Escalation trigger outputs
Property | Description | Example |
escalation.reason | Whether the escalation was triggered by an application or a person (ACTIVE) or by a timeout (PASSIVE). | ACTIVE |
escalation.escalationType | The type of escalation: PEER, MANAGEMENT, or NONE | PEER |
escalated.at | Date and time of the escalation in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
escalated.by.id | For active escalations, the unique identifier (UUID) of the recipient whose response manually escalated the event. | e1e427bb-770f-4d47-aa4d-efdd8b64089c |
escalated.by.targetName | For active escalations, the username of the recipient who manually escalated the event. | mmcbride |
escalated.by.firstName | For active escalations, the first name of the recipient who manually escalated the event. | Mary |
escalated.by.lastName | For active escalations, the last name of the recipient who manually escalated the event. | McBride |
escalation.group.id | Unique identifier (UUID) of the group in which the escalation occurred. | afd56311-86cd-476f-a6ae-51e3d8cadbe0 |
escalation.group.targetName | The name of the group in which the escalation occurred. | Deneb Service Team |
escalation.group.status | The status of the group in which the escalation occurred. | ACTIVE |
escalation.from | An array containing the id (UUID), recipientType, status, and targetName of each recipient at the escalation level from which the escalation occurred. Devices are reported as a person recipient type, corresponding to the device's owner. | c68bfa2f-4539-40a9-9e96- 185b7ecde7ff mmcbride PERSON |
escalation.to | An array containing the id (UUID), recipientType, status, and targetName of each recipient at the escalation level to which the escalation occurred. Devices are reported as a person recipient type, corresponding to the device's owner. | 98555e21-b7ff-479e-a264- 3e96815fb03d NOC GROUP |
To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.
Targeted recipient failures trigger
The Targeted Recipient Failures trigger initiates a flow when none of the targeted recipients could be immediately notified for an event. Outputs include the type of failure, the first 100 targeted recipients, and the total number of targeted recipients.

Examples of when to use this trigger:
- Automatically notify a chat room that an event isn’t currently routing to on-call resources.
Targeted recipient failures trigger output details
Property | Description | Example |
targeted.triggerType | The type of targeting attempt for which no recipients could be notified: INITIAL_EVENT, TIMED_ESCALATION, or MANUAL_ESCALATION | TIMED_ESCALATION |
targetingFailed.at | Date and time of the targeting failure in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
targeted.totalRecipients | The total number of targeted recipients. | 35 |
targeted.recipients | An array containing the id (UUID), recipientType, status, and targetName of each recipient (up to the first 100 targeted recipients). Invalid recipients are returned with a status of "INVALID". | f51d0fa3-6712-4b4e-9da4-b8a631f8b8c1 DEVICE ACTIVE mmcbride|Work Email |
To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.
App triggers
Flow Designer has built in triggers to receive and parse request from common applications. See our built-in app instructions for information on these triggers:
HTTP Request trigger
HTTP Request triggers initiate a flow when xMatters receives a POST request to the trigger's URL. The HTTP trigger parses the payload from the incoming HTTP request, then extracts information from the payload and maps it to user-defined outputs of the trigger to be available as inputs to later steps in a flow.

What triggers it: xMatters receives an incoming HTTP request from an external system to the trigger's URL.
What information is in the outputs: Properties or information from the request mapped to outputs by the user that created the trigger.
Examples of when to use this trigger:
- To inject information into xMatters from any system capable of sending a POST request.
HTTP request trigger output details
HTTP triggers do not have a standard set of outputs because the outputs, and mapping of request properties to these outputs, are defined by the user that created the trigger.

Each HTTP trigger is authenticated independently, using the authentication method set by the trigger creator (unless the creator set the trigger to allow all methods).
Depending on the allowed authentication methods, you might need to select the authenticating user that should be used to authenticate requests. Regardless of the method chosen, any requests submitted to the trigger URL have the same permissions in xMatters as the authenticating user, whether that user was set in the step or their credentials were included in the request.
Authentication methods
When creating an HTTP trigger, you can allow only one of these methods to be used or select the Allow all methods option to allow any of them to be used. It's recommended that you choose the most secure method the calling system supports
URL Authentication |
xMatters generates an API key unique to the authenticating user selected when the trigger is configured and appends that API key to the trigger URL. Any requests submitted to this URL have the same permissions in xMatters as the authenticating user. The URL does NOT grant permission to log into the web user interface. URL authentication is the least secure method of authentication because anyone with access to the URL can trigger the flow. This authentication method is not recommended unless the flow does not need to be secured. |
Basic Authentication |
Basic authentication requires the calling system to store the credentials of an xMatters user with permissions to access the workflow the trigger belongs to. If the user resets their password in xMatters, you must also update the calling system with the new password for it to continue to be able to trigger the flow. |
API Key Authentication |
API Key authentication uses a randomly generated API key and secret which are then stored in the calling system. To authenticate a request using API key authentication, use basic authentication with the API key as the username and the secret as the password. An API key credential has the same permissions within xMatters as the associated user, and can authenticate any request as that user, including to trigger a flow, submit requests to the xMatters REST API, or initiate an integration. You cannot use the API key and secret to log into the xMatters web user interface. If your account does not have an API key credential, you can create a new set of API Key credentials in your profile (or the profile of a specific integration user). You can view your API key credentials or the credentials for any user you supervise on the API Keys tab within the user profile. |
OAuth Authentication |
OAuth authentication requires you to provide the OAuth credentials of an xMatters user to trigger the integration. For more information about using OAuth with xMatters, see OAuth authentication. |

Once you create and share an HTTP trigger, you can reuse it in any flow. You can also create new versions of the trigger as your needs change.
Step 1: Create the HTTP trigger
When you create a new custom HTTP trigger, the first thing to do is set up how it appears in the palette: the name, description, and icon.
- On the Triggers tab of the palette, click Create HTTP Trigger. This opens the New HTTP Trigger dialog box.
- On the Settings tab, give the trigger a name and description. These appear in the palette, and help people know what this trigger does and if it's something they should use. People can give the trigger a different label when they add it to the canvas.
- To change the icon used for the trigger, click Select Image. This opens an image library with a selection of icons, including a few default ones and any icons you've already added for your xMatters company.
- Click an icon in the library to select it. To add a new icon to the image library, click the Choose a file to upload link and browse to the file you want to use.
- For the best appearance on the canvas, we recommend using images that are 36 x 36 pixels. The maximum file size is 250 KB, and you can use a variety of common image formats: jpg, jpeg, gif, and png.
- Once you've selected your image in the Image Library, click Select to go back to the step settings.
- Set the step state and version information.
- Select the Run Location where the step is allowed to run. Allowing the step to run on an xMatters agent lets it update and retrieve information from systems behind your corporate firewall.
- Cloud: The step can only run in the cloud.
- xMatters Agent: The step can only run on an xMatters agent.
- Both: The person using the step in a flow can select where the instance of the step will run when they configure it.
- Select the authentication method you want to allow the step to use. You can also select Allow all methods if you want users to be able to pick the method used when they configure the trigger.
Step 2: Create the outputs
When you define the outputs, you're deciding what information this trigger should provide to steps further downstream. For properties from the request to be available to steps later in the flow, you need to use the script to map them to the outputs of the trigger (see the next step).
- On the Outputs tab, click Add Step Output to create a new output.
- Enter a name for the output. This name can be used to reference it in the script editor, and appears in the step setup screen where people can drag it into the input of a connected step.
- Click Add Step Output for each additional output you'd like to create. To delete an output, click the 'x' icon next to the output.
- When you're done adding outputs, click Save.
Step 3: Map the outputs
The Script tab is where you define the internal logic that takes the HTTP request from another application, transforms the incoming information, and maps it to the outputs. When you create a new HTTP trigger, the script only brings what is included in the payload. Properties of the form associated with your flow canvas are not available as outputs because HTTP triggers do not use the form to create an event in xMatters. You need to map properties from the request to outputs of the trigger to use these properties in steps in your flow.
The Script tab includes an example script showing how to parse the payload from an incoming HTTP request, then extract information from the payload and map it to outputs. You can use it as a template and customize it to work with your flow. The trigger's built-in request object enables you to access elements of the request, including the payload contained in the request body and any URL parameters.

The following instructions describe how to add and configure an HTTP trigger in your flow.
HTTP trigger authentication
Each HTTP trigger is authenticated independently, using the authentication method set by the trigger creator (unless the creator set the trigger to allow all methods).
How to configure an HTTP trigger
- On the Triggers tab of the palette, under HTTP Request, drag the custom HTTP trigger you'd like to use onto the canvas.
- You can filter the HTTP triggers by triggers you own, triggers others have shared with you, or all triggers you have permission to use.
- Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
- Change the Trigger Label if you'd like to customize the trigger's name for your flow.
- If the step allows any authentication method, select the method you want to use in the Initiation settings.
-
If required by the authentication method, select whose credentials you'd like to use to trigger the flow. Click the list to display users who can authenticate the trigger, or start typing a username into the search field to filter the list (two characters are required).
- Users only appear in this list if you supervise them (or are a company supervisor) and they are assigned a role with the REST Web Services function.
- Click Run Location to set where the trigger runs. This tab only appears if the trigger is allowed to run on an xMatters agent.
- Select the location where you want this step to run: Cloud or xMatters Agent.
- If you set it to xMatters Agent, select one or more agents from the list of available agents. To select an agent from the list, you must be a registered user of the agent and it must be version 1.4.1 or later. If you don't have any agents configured, click Add an xMatters Agent to go to the Agents page, which has instructions for installing the agent.
- Back on the Settings tab, click Copy to save the trigger URL to your clipboard.

To initiate the trigger, send a POST request to the trigger URL using the requirements of the configured authentication method:
- URL Authentication: Send an HTTP POST request to the trigger URL.
- Basic Authentication: Send an HTTP POST request to the trigger URL using basic authentication and an xMatters username and password.
- API Key Authentication: Authenticate the request using basic authentication and set the username to the API key and the password to the secret.
- OAuth Authentication: Include an access token in the request header. A client ID is required to obtain and refresh access tokens in the xMatters REST API. You can find the client ID for your company under Workflows > OAuth. For more information about using OAuth with xMatters, see OAuth authentication.
You can also click View Instructions for instructions on how to trigger the flow.
If you want to view the results of the trigger initiation in the Activity panel, make sure you've connected steps to the trigger. If the trigger isn't connected to anything, no activity information appears.
Email trigger
An email trigger initiates a flow when you send an email to xMatters. When xMatters receives an email from a valid sender, it initiates the corresponding flow and uses information from the email to set values for outputs of the trigger, available as inputs to later steps in a flow. Outputs include the email sender, headers, addressees, subject, and body.
If you have an existing integration using the legacy email initiation, we automatically converted to a flow consisting of an email trigger and a create event step.

Examples of when to use this trigger:
- To inject information from any external system capable of sending an email message to xMatters; this might include custom applications or almost any cloud-based application, monitoring system, social media platform, e-commerce platform, or customer relationship management tool.
Email trigger output details
Property | Description | Example |
email.to | All the email addresses included in the To: field of the email that triggered the flow. |
[0]: mmcbride@hq54b.mycompany.xmatters.com [1]: DatabaseAdmins@hq54b.mycompany.xmatters.com |
email.sender | The user ID of the email initiator. | integrationUser |
email.subject | The subject of the email message. | IT Alert: Database Unavailable |
email.htmlBody | The content of the email sent as HTML. | <html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"> <head> ... </html> |
email.plaintextBody | The content of the email sent as plain text. | The Oracle Database is not available. |
email.headers | A JavaScript object containing the headers of the email. |
|
email.senderIp | IP address of the email initiator. | 192.0.2.132 |
email.recipients | Target names of users, groups, or dynamic teams included in the To: field of the email that triggered the flow. | mmcbride,DatabaseAdmins |
If you want to pull out information from the email body to make the details available as inputs to steps downstream, you can create a custom email parser step. Check out the instructions on our support site.

The unique email address that you use to initiate a flow is created from a target name, the trigger ID, and hostname of your xMatters deployment in the following syntax:
<name>@<triggerID>.<hostname>
- <name>: The name can be the user ID of a specific user or the name of a group or dynamic team. For example, mmcbride@hr54b.mycompany.xmatters.com or DatabaseAdmins@hr54b.mycompany.xmatters.com.
- <triggerID>: By default, the trigger ID is a randomly generated combination of alphanumeric characters. You may want to change the trigger ID to be more readable, or you may want to change it to something hard to guess for security purposes. The trigger ID must be unique within your company.
- <hostname>: The URL that you use to access the xMatters web user interface without the "https://". For example, the hostname for https://mycompany.xmatters.com is mycompany.xmatters.com
If your hostname includes a regional or specific instance indicator, do not include it in the target email format. For example, if the URL you use to access xMatters is mycompany.na1.xmatters.com, do not include the na1 portion of the URL in the email address. Use just mycompany.xmatters.com.
You can find the target ID and sample email address for an email trigger on its configuration screen in Flow Designer.
Understanding how Flow Designer uses trigger email recipients
Email triggers in Flow Designer do not create an event in xMatters when they are initiated. The target name of the user, group, or dynamic team named in the initiation email is mapped to the email.recipients output of the trigger, which you can use as an input to later steps in your flow, such as for the recipients of a xMatters Create Event step. To include more than one target name in the email.recipients output, add multiple addresses to the To: line of the email (one for each user, group, or dynamic team), using the format described above.
For example, if the To: field of your trigger email includes the following user, group, and dynamic team:
To: mmcbride@hr54b.mycompany.xmatters.com; DatabaseAdmins@hr54b.mycompany.xmatters.com; AllEmployees@hr54b.mycompany.xmatters.com
Then the email.recipients output would include this comma-separated list of target names you could use directly as input to the recipient field of an xMatters event step:
mmcbride,DatabaseAdmins,AllEmployees
xMatters accepts 9 and 10 character BATV-encoded email addresses.
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 you plan to include them on a trigger initiation email and use them as recipients inputs on another step in a flow.

The email trigger lets you select whether initiation emails can be sent from any email address or are only accepted when they are sent from an email address assigned to a device in xMatters.
For example, lets say Mary McBride has a work email device configured in xMatters with the address mmcbride@your-company.com. She also has a personal maryrocks@cloud-email.com address, but it's not assigned to a device in xMatters.
If the trigger is set to allow initiation from any address, Mary could send an email from her maryrocks@cloud-email.com address to initiate the email trigger and execute the connected flow. The flow authenticates using the Authenticating User selected in the trigger settings (which may or may not be Mary).
If the trigger is set to only allow initiation from an address associated with an email device in xMatters, Mary has to send the email using her mmcbride@your-company.com email; emails from maryrocks@cloud-email.com are rejected. When Mary sends an email from a valid email address, the trigger is initiated and the flow executed using her credentials.

- Drag the trigger from the palette onto the canvas.
- Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
- Change the Trigger Label if you'd like to customize the trigger's name for your flow.
- Select the authentication method:
- Send from any email: An email sent from any email address will trigger the flow. The flow runs using the credentials of the user selected in the Authenticating User field.
- Send from an xMatters email device: Only emails sent from an address associated with a valid xMatters device will trigger the flow. The flow runs using the credentials of the user associated with the email address.
- Optionally, customize the Trigger ID. You may want to change the trigger ID to be more readable, or you may want to change it to something hard to guess for security reasons.
- Click Copy Address to copy the trigger's email address to your clipboard, so that it's available when you're configuring an external system to email xMatters, or to share with other users who want to initiate the flow by email.
- The sample email address shows how to initiate the trigger with your target name. When you initiate the trigger by email, you can replace your user ID with a different user ID, group name, or dynamic team name.
- If you'd like, you can also click Test Email to automatically open your default email program so that you can send a test email to your trigger's email address and see if it triggers your flow (if you selected Send from an xMatters email device, make sure your default email is associated with an email device).
- Click OK.
To give you the flexibility to trigger a flow without creating an event, the email doesn't automatically initiate an event in xMatters. If you want to create an event when the Email trigger is initiated, simply add a Create Event step to your flow, either right after the email trigger or after additional steps that gather more information to enrich the event notification.

How can I assign an external system a valid email address in xMatters?
This is only applicable if you want to limit the trigger initiation to addresses associated with an email device in xMatters.
To enable xMatters to recognize emails from your external system, do one of the following:
- 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 access to the flow, 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 an email address that is authorized to initiate the flow.
Check the Devices screen in a user's profile to confirm that the email address that you are sending the initiation email from matches the address for one of their email devices.
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.
What happens if I 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. Users, groups, or dynamic teams added to the Cc: and Bcc: fields are also included in the email.recipients output.
The sample email address shows how to inject my own target name with the email. How can I add other uses, groups, or dynamic teams to the To: field so they're included in the email.recipients output?
- To add another user instead of yourself, use their user ID before the @ symbol in the trigger email address.
- To send to a group or dynamic team, use the group or team name before the @ symbol. (Spaces or quotation marks in the name of the group are not recommended.)
- To target multiple recipients, use multiple addresses on the To: line.
What happens if I put email addresses for different flows in the same email?
xMatters will trigger each flow that you provided a trigger email address for in the To: field of the email, as if you had emailed the trigger addresses separately.
What happens if you include "regular" (non-trigger) email addresses in the To: line?
If you include an additional email address not associated with a flow trigger in the To: line along with one or more trigger email addresses, you'll send that email address a copy of the email. The flow is triggered but that email is not be included in the trigger outputs. Email addresses must follow the trigger email initiation format to be included in outputs of the trigger.
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 mmcbride@traveladvisory.example.xmatters.com might be changed during transit through your email server to something more like mmcbride@us1-west-1.mail_traveladvisory.example.xmatters.com.
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.
Form trigger
This is part of the adaptive incident management toolset and is not yet available in all instances.
The form trigger lets you and your team initiate flows by filling out and submitting a Flow Trigger form (you need a form of this type in your workflow to configure a form trigger). This lets you initiate a flow without sending notifications, if that doesn't suit your process.
What triggers it: When a flow trigger form is submitted.
What information is in the outputs: Properties and parameters defined in the layout of the associated flow trigger form. The values at runtime depend on what's defined on the form layout and what's entered when the form is submitted
Examples of when to use this trigger: This step is primarily used in created your own custom incident management response flows. To initiate incidents when the associated form is submitted, connect an Initiate incident step to the form trigger.

- Drag the Form trigger from the palette onto the canvas.
- Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
- Select the form to use for initiating the flow (the form description, if it exists, appears below the name) and click Apply.
- You can't switch the form used by the step after you click Apply; if you decide you want to target a different form, delete this instance of the step from the canvas and add a new form trigger.
- The step takes its label from the associated form.
- Click Sender Permissions to allow additional users to submit the associated form.
- You can select either users or roles; if you select a role, any users assigned that role can submit the form (for example, "Incident Managers"). Make sure you also set the same sender permissions on the messaging form associated with any connected Create Event steps; otherwise the flow might encounter errors at runtime.
- Select whether to enable this form in the Web UI — this allows people to use the form to initiate an incident from the Incidents list or the widget on the dashboard.
- Currently, you cannot submit Flow Trigger forms from the mobile app.
Sender permissions and enabling the form can also be set on the associated form.