The mail API allows you to set properties on tickets by adding commands to the body of your email response to a Zendesk notification or to create a new ticket. Only agents can use the Mail API. If these commands are used by end-users, Zendesk will ignore them.
Here's an example of an agent reply to an email notification.
An agent can also create a new ticket by addressing a new email to the support email address of their Zendesk account and adding Mail API commands.
When Zendesk receives an email from an agent, we'll check to see if any commands are present at the top of the email, and execute the commands on the relevant ticket.
Note: You can only update an existing ticket by replying to an email notification for that ticket. In other words, you can't create a separate new email message and reference an already existing ticket. This is because Zendesk needs the ticket ID, which is contained in the Reply To email address (as shown in the graphic above).
The Mail API simply scans the top of your email for the list of commands you want Zendesk to perform.
These commands follow this pattern:
If, for example, we wanted to set the status of a ticket, we can do so using this command:
Each line should be separated by a new line. If we wanted to set the status and the assignee, for example, we can do:
After this, you can simply put in your normal email content after your block of commands.
For the more regularly used commands, we've added some quick and easy ways to use them, called short commands. These are usually one word commands that don't need a value. If they're supported by a particular command, they'll be highlighted below.
List of all Commands
Below is a list of all the supported commands you can add, one line by one line, in a response to a Zendesk email notification.
Valid values are open, pending and solved. #assignee must be set in order to set a ticket to Solved.
Short syntax:#open #pending #solved
Sets the requester of the ticket. This can either be the users 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.
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).
Sets the priority of the ticket. Valid values are low, normal, high and urgent. Note, in order 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
Set any tag on the ticket, which can be separated by spaces or commas.
Note that this sets the tags, removing 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 any invalid commands, or values, are given to Zendesk then that command or value will be ignored by Zendesk.
An example showing all of the commands
This example shows all of the commands.
The above example will do the following to ticket #178:
Set the status to open
Set the group to “Support” and the assignee to the agent with “firstname.lastname@example.org” as their email address
Set the priority to “normal”
Set the type to “question”
Set the tags to “help” and “api”
Set the visibility of the comment to “private”
Add a new comment with “Hello world!” to the ticket, which combined with the above command will not be visible to the requester.