The mail API allows you to set ticket properties by adding commands to the body of an email response to a 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 their support address. This kind of email creates a new ticket.
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 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. |
#group |
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 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 if a comment update on a ticket is public. Only usable when updating a ticket. The default value for public tickets is true, meaning that anything else you put in the body of the email will be seen by the requester. 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, they're ignored by Zendesk.
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
- 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.
83 Comments
Is there any option to have this viable for set users without them being agents?
Example: A company is using a third party helpdesk and wants them to be able to send emails into a mailbox that generates zendesk tickets w/the appropriate fields using the mail API. This third party helpdesk would be whitelisted for zendesk incoming ticket creation but would not be agents themselves or do anything within the actual ticketing system.
Thanks
hey RTB,
As the docs mentioned, the Mail API is only usable by agents in your Zendesk instance. To do what you're looking for, I suspect you would want to connect a mailbox to ZD for this partner and have fields assign by business rules. This could get tedious if there's a lot of conditions/cases you need to check.
If the 3rd party uses Zendesk, you can also use ticket sharing.
The third party uses there own proprietary ticketing system which we will not have access to. We really don't need the T1 support group to have access to our ticketing system at all we just need an easy method for them to submit the tickets to us and pre-populate a few ID fields.
If we make them all agents we are using licenses that cost $$ just to forward us data and create a ticket.
I figured mail api would be simple and easy but if they require the use of a license that is a pricey method of ingesting data.
Hey RTB,
It may be worth setting up a ticket form for this 3rd party to submit tickets through so they can populate the fields themselves.
Otherwise, they'd need to forward the information to your support address you've set up on your account and your agents will need to populate the fields themselves.
Let me know if you have any other questions for me!
Thanks Brett, I will review the ticket form option.
As an alternative do you see any issues with simply having our third party support team create a shared exchange account and we could add that account as an 'agent' thus allowing them to send from that mailbox to our ingestion box using mail api? This would allow the 1-3 tech's to send us mail using the mail api format without the mail being rejected presumably while retaining the simplicity of using a mail api template.
Thanks
Hey RTB,
That could work, however, you'll want to designate one user to this agent license so they can use the mail API. Giving multiple users access to a single agent license goes against our Master Subscription Agreement so you'll just want to be careful with that.
Let me know if there's anything else I can assist with :)
Hello,
Is there a method to merge tickets via the Mail API?
Hey Dave,
At this time there's no way to merge tickets using the Mail API. You'll most likely need to use the Support API to merge tickets in this case.
Let me know if you have any other questions!
Hi, any update on the ability to add a #cc tag?
Currently the only way to cc a client into a ticket from an email is to add them to the cc field in the actual email. They will then get two emails:
A #cc tag would mean you don't need to cc the email itself to them, which would mean they only get the email generated from Zendesk.
Hey Alex,
No update to provide currently but I do agree this is an excellent idea! I'll be sure to pass this feedback along to the appropriate team :)
Cheers!
Hi Brett,
That's great to hear.
Perhaps a request too far, but it would be nice if at the same time as the #cc tag above, cc'ing someone into the actual email didn't cc them into the zendesk ticket.
An example of our ideal workflow is:
Currently, our workflow is:
Thanks Brett,
Cheers,
Alex.
Appreciate the additional information Alex! I'll mark this as feedback so our Product Managers can take a look.
Cheers!
Hi Brett,
Please disregard that second request, I've just realised that we can bcc the email to our general support email - this will send the email to them, but not cc them into the zendesk ticket (the effect we were after).
The first request for the #cc tag would be great though!
Cheers,
Alex.
Hi there!
Is there a way to ADD a tag to a ticket through the mail API without removing the existing ones?
Currently, using #tag removes all other existing tags in the process.
thank you
Bart Brosens,
I'm not aware of a way to add a tag without replacing the existing set using the Mail API directly, but you can use triggers that look for certain keywords in your message to apply those tags once the message is received.
It may be worth submitting this as a feature request in the Support Product Feedback topic in the Community.
Good afternoon,
Our agency started using Mail Commands a while back to great success. However, as of this afternoon suddenly, the Commands are showing up in Public Comments received by customers, contrary to what this article says should be the norm. Here is an example (fairly basic):
Original message (via Outlook):
Here is what the customer saw below:
Any advice on what may be suddenly causing this?
Hi RJ Hines,
Is the email address that is sending in the message tied to an end-user or agent? Often times in these cases it is an agent that is using an alternate email address that is not tied to their agent profile, and the Mail API is only for users with agent permissions.
Thanks!
Good morning Ben,
The email address sending the messages are licensed Agents.
Hi RJ,
Well that is odd. I'm going to create a ticket for you so that our Support team can take a closer look.
Thanks!
Hi Jennifer,
Here is a bug that is impotent for us, regarding the #solved Zendesk Mail API:
Steps to reproduce:
I could reproduce it with other combinations, like #note #solved, or #solved #public.
Please let me know when it should be fixed.
Thanks
An update: I sent multiple Mail API in the same line. Sending each mail API in a separate line (as documented) solves the issue.
Hello all,
Are you planning on supporting custom fields at some point?
Thanks in advance.
Hello Alejandro Lopez,
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.
Best regards.
Please sign in to leave a comment.