The mail API allows you to set ticket properties by adding commands to the body of an email response to a Zendesk notification, or of an email creating a new ticket. Only agents can use the mail API. If these commands are used by end-users, Zendesk ignores them.
Here's an example of an agent setting the status and assignee of a ticket in a reply to an email notification:
An agent can also use the commands in a new email sent to the support address of their Zendesk account. This kind of email creates a new ticket.
The mail API simply scans the top of your email for the list of commands you want Zendesk to perform.
The commands must be in plain text, not HTML, and follow the following pattern:
If, for example, you want to set the status of a ticket, use this command:
Each line should be separated by a new line. For example, if you want to set the status and the assignee, write the commands as follows:
Enter the body of your email after the block of commands.
Below is a list of all supported commands that you can add, one line at a time, to the body of a valid email. The list also includes short commands, one-word commands for regularly used commands that don't need a value. For example, you can use the short command #solved instead of #status solved.
Valid values are open, pending and solved. Note: #assignee must be set in order to set a ticket to solved.
Short syntax: #open #pending #solvedNote: The #solved command only works for tickets that don't have required fields that the agent must fill out before the ticket can be solved.
|#requester||Sets the requester of the ticket. This can either be the user's ID in your account, or simply their email address. If they don't already exist in your account, Zendesk will create it for you.|
|Assigns the ticket to a group. Valid values are the name of the group or the ID of a group.|
|#assignee||Assigns the ticket to an agent. Valid values are the email address of the assignee or the Zendesk ID of the assignee (obtained via e.g. a REST integration).
Using this command automatically makes you a collaborator (cc) on the ticket.
Sets the priority of the ticket. Valid values are low, normal, high and urgent. Note: To set a priority, you must also set a ticket type (see below)
Short syntax: #low #normal #high #urgent
Valid values are incident, question, task and problem.
Short syntax: #incident #question #task #problem
Sets any tag on the ticket, which can be separated by spaces or commas.
Note: Setting the tags removes all previously set tags on that ticket.
Sets if a comment update on a ticket is public. Only usable when updating a ticket.
The default value is true, meaning that anything else you put in the body of the email will be seen by the requester.
Short syntax: #note (meaning private comment)
If you enter any invalid commands or values, they're ignored by Zendesk.
In this example, the agent uses all the commands.
The email does the following to ticket #178:
- Sets the status to open
- Sets the group to “Support” and the assignee to the agent with “firstname.lastname@example.org” as their email address
- Sest the priority to “normal”
- Sets the type to “question”
- Sets the tags to “help” and “api”
- Sets the visibility of the comment to “private”
- Adds a new comment with “Hello world!” to the ticket, which combined with the above command will not be visible to the requester.