Using the Mail API to update ticket properties from your inbox

What's my plan?

The Mail API allows you to set ticket properties by adding commands to the body of an email response to a notification or an email creating a new ticket. Only agents can use the Mail API. If these commands are used by light agents or 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 their support address. This kind of email creates a new ticket.

When Zendesk Support receives an email from an agent, it checks to see if any commands are present at the top of the email and executes 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 email message and reference an already existing ticket. This is because Zendesk Support needs the ticket ID, which is contained in the Reply To email address, as shown in the image above.

Syntax

The Mail API simply scans the top of your email for the list of commands you want to perform.

The commands must be in plain text, not HTML, and follow the following pattern:

#command value

If, for example, you want to set the status of a ticket, use this command:

#status solved

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:

#status solved


#assignee [e-mail]

Enter the body of your email after the block of commands.

Note: There should only be one space between your command and value.

Command reference

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.

Note: Using custom field names as commands is not supported.

Command	Description
#status	Valid values are open, pending, and solved. Note: #assignee must be set in order to set a ticket to solved. Short syntax: #open #pending #solved Note: 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 be the user's ID in your account or their email address. If they don't already exist in your account, Zendesk will create it for you.
#group	Assigns the ticket to a group. Valid values are the name of the group or the ID of a group. This command is especially useful for forwarded emails. When an agent forwards an email to Zendesk, by default the resultant ticket is either unassigned or assigned to the agent's default group. (See Passing an email to your support address.) Agents can use this command to automatically assign the forwarded ticket to the specified group instead.
#assignee	Assigns the ticket to an agent. Valid values are the email address of the assignee or the Zendesk Support ID of the assignee (obtained via e.g. a REST integration). Using this command automatically makes you a collaborator (cc) on the ticket.
#priority	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
#type	Valid values are incident, question, task, and problem. Short syntax: #incident #question #task #problem
#tags	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.
#public	Sets a comment update on a ticket to public. Only usable when updating a ticket. The default value for public tickets is true, meaning that the requester will see anything else you put in the body of the email. The default value for private tickets, such as tickets created by light agents, is false. Short syntax: #note (makes future comments from that agent private for that ticket, unless reversed by #public on each individual comment)

Invalid commands

If you enter any invalid commands or values, Zendesk ignores them.

Example

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 “[e-mail]” as their email address
• Sets 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.