Associating email messages with incidents

You can create a new incident based on an email message or associate an email message with an existing incident. In either case, the following occurs:
  • Once an email message is associated with an incident, it cannot be associated with a different incident.
  • Once the call to associate the email and incident is made, the top-level incident variable is populated with the details of that incident and can be modified.
  • Scripts can only be run against email messages in the Mail Inbox, which is accessible by clicking Inbox in the menu bar. Once an association is made, that email is removed from the Inbox.

Use createAssociatedIncident to create a new incident.

Use associateWithIncident(incident) to associate an email with an existing incident. You need to use helper.findIncidents() to look up an existing incident.

The following script is an example of associating an email with an existing incident, or creating a new incident if one does not exist.
# Attempt to look up an existing incident (whose name contains the string "ABC123")
query_builder.contains(, "ABC123")
query =

incidents = helper.findIncidents(query)

if len(incidents) > 0:
  # found it! associate the email message with that
  # no match, so create a new incident (owned by the specified user)
  emailmessage.createAssociatedIncident("ABC123", "")