Suite | Team, Growth, Professional, Enterprise, or Enterprise Plus |
Support | Team, Professional, or Enterprise |
Verified AI summary ◀▼
Use the Mail API to update ticket properties directly from your inbox by adding commands to your email. This feature is available for agents and allows you to set ticket status, assignee, priority, and more. Commands must be in plain text at the top of your email. Invalid commands are ignored, and existing tickets can only be updated by replying to their email notifications.
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.
Tickets that are created or updated with the Mail API are handled through the email channel.
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 jake@zendesk.com
Enter the body of your email after the block of commands.
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
.
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:
#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: |
#type |
Valid values are incident, question, task, and problem. Short syntax: |
|
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: |
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 “jake@zendesk.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.
28 comments
Gail Day
Any chance of introducing a CC (copy) Mail API tag? We have a third-party form that creates tickets via email, and this would be useful.
0
Julian
On Dec 22, 2021, Jeff C said:
Yet, the article says
What would be, now, a turnaround to this scenario:
Goal:
When a partner company forwards a user request to my Zendesk, the forwarded email often includes internal information meant only for my agents and not for the requester.
Need:
I want the first message in the conversation (the forwarded email) to be created automatically as an internal note, so it is not visible to the end user.
Thank you for your ideas.
0
Axel de Jong
This is something we too would really appreciate: some kind of trigger to allow to set the organization on email tickets for users with multiple organisations.
1263792605130 did you ever find a way to achieve this?
0
Justin Near
We have several clients with multiple organizations. I'm not seeing “Organization” in the placeholder list, but I'm also not seeing a way to change organization on a ticket with a trigger. Is there a way to change the organization using a placeholder and/or some other method while forwarding an email?
0
Dainne Kiara Lucena-Laxamana
Hi 5094134994970
That's rather odd. I went ahead & created a ticket to look into that Email trail using the latest comment placeholder. Please keep an eye out for our Email
0
Kiran Yadav
Hi Team, if we are replying to the requester about the ticket and the requester is replying back through their email, is it possible that the requester see only the latest comment and not the other trail mail comments. I have tried using the latest comment placeholder in the trigger but still if the agent replies back the comments are visible in the trail mail
0
Sriram Parthasarathy
Support team, are you planning on getting html-formatted tags to work? We are not able to ask our agents (who all use Outlook) to make sure they switch to plain text email every single time they want to reply to a ticket and use mail api for changing the assignee, status, or adding a note.
0
Patrick Lanwehr
Hi Mike,
just check my comment from the 29.06.2023
I have already added the link.
0
Mike DR
0
Joyce
#brand
is not a supported command for Mail API. All the supported Mail API commands are listed in the Command reference topic of this article.As a workaround, you can use the
#tags
command to add a ticket tag and use this tag as a condition in a trigger to set the ticket brand.Hope this helps.
1
Sign in to leave a comment.