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 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.
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:
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
Valid values are open, pending, and solved. Note: #assignee must be set in order to set a ticket to solved.
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.
This command is not available for light agents.
||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.
||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.
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)
Valid values are incident, question, task, and 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 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.
If you enter any invalid commands or values, Zendesk ignores them.
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 “email@example.com” 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.
Are you planning on supporting custom fields at some point?
Thanks in advance.
We have no recent updates to announce at this time, but I would recommend posting in our product feedback forums. This is where our devs share insights on future roadmaps and share their perspective on user-product requests.
Does setting the On-hold status work? I have tried.
and that doesn't seem to work.
I'm afraid that the Mail API does not support setting the On-Hold status. The only workaround I can think of using the Mail API would be to include a specific comment string or keyword, and then create a trigger that looks for that phrase or keyword and if it finds it, sets the status to On-Hold.
(I'd definitely not recommend using the Mail API #tags command, as that will strip any previous tags from the ticket.)
Aside from this, logging in to the agent interface, or using the Zendesk Support mobile able would be my other suggestions.
Are there plans to support commands in HTML anytime soon? I'm working with a monitoring software that is only able to send emails via HTML, so none of my Mail API commands work...
The #public command doesn't seem to be working.
My agent email is sending in a ticket trying to set #requestor and trying to make the ticket initially start as an internal ticket.
Is there any way to accomplish this?
The #public comment is only usable when updating a ticket and not upon starting or creating a ticket. That said, I am afraid there is no other way other than if the agent creating the ticket is a Light Agent.
I'm noticing that using #note applies to the whole communication thread, affecting future responses from agents on the ticket as well. Is there a way to only make one comment update private, but then have future responses to go back to public (back to the default)?
Thank you for reaching out to Zendesk Support.
In regards to your concern, you can use the #public false like the example above suggested to set the visibility of the comment into private.
I am able to email our support address with several of these commands and it seems to create the ticket correctly -- with one exception.
When I set tags using the #tags command, I am seeing that the tags are indeed set for this ticket, but the #tags line in the email is not removed so my initial ticket comment starts with #tags .... . All other command lines are removed correctly, but not the #tags one. I tried moving it up and down my command "list" but that one still remains.
Can you check with the devs to see if this is a known issue?
I have performed the same test on adding the tags both and standard and Agent Workspace. It seems to work as expected. Can you try it again? If in case you have the same result, contact support directly so we can investigate further.
It is very unfortunate that it is not possible for an agent to link an email message from his/her private mailbox to an existing ticket using, for example, the syntax #ticket 123
Any chance of getting those custom field name updates working from the email?
Hi, is this feature still working? I tried these commands but they did not work. Do I have to enable any setting?
Have you checked if the new message composer in your email client is set to plain text format? As noted above –
It may also be worth checking from the event audits to confirm if no triggers fired to change the status and the assignee after the commands were executed.
Please sign in to leave a comment.