Updating ticket properties from your inbox Follow

all plans

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.

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.


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.

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


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.
 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.


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.


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


Valid values are incident, question, task and problem.

Short syntax: #incident #question #task #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 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)

Invalid commands

If you enter any invalid commands or values, they're ignored by Zendesk.


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.
Have more questions? Submit a request


  • 1

    The short syntax is helpful. What are the chances of adding CC's using the API. I know that I can do it by adding the people to the actual CC field in the email, but the downside to this is that the people getting added get two e-mails -- my direct email reply (will all the other Mail API commands exposed, and which they might reply directly to breaking the chain) and the notification from Zendesk.

    Would like to be able to do this:

    #assignee joeschmo@fake.com

    #cc janedoe@fake.com,jimbob@fake.com

  • 0

    This looks strikingly familiar to something we have implemented in our triggers and have been using for a few years (we call them commands also).  The only difference is we use 'z command' to issue a command instead of '#command xyz'.  Glad you guys are integrating this into the main system, it is very powerful for controlling tickets through the inbox!

    That being said I do have 2 suggestions (from my experience using something like this for the past 2+ years):

    1.  It would be nice to be able to create custom commands (similar to creating triggers).  The short syntax's are great (like #public or #note, awesome!), but it would be nice to define our own as well.  For instance one of our commands is 'z assign to me', or 'z assign to Rob', which is a lot nicer than having to write '#assignee rob.werjsas@xyzdomain.com'.  It makes using the commands feel a lot more natural (especially within email).  This can also be especially helpful for common repetitive tasks.  For instance, if what you gave as an example was something that our agents did repeatedly (several times a day), it would be much easier to define a custom command #doThis (which would perform all 7 steps) than have to continuously hammer out 7 lines of commands several times a day.

    2.  The only other thing that would be nice is being able to set the delimiter/token to begin a command.  Like I said, we just use 'z command', which is a lot easier than trying to reach up to the # key five times per email (especially for something that is done often).  It flows a lot better and feels more natural when writing email (flows more like a sentence).  If that is a problem for someone maybe they could change to use a different token like 'zz' or something

  • 0

    Does the curly bracket API format still work as well?

  • 0

    @Pete: No, not in email. Only the documentation above will apply to email.

  • 0

    What is the format for creating a new ticket via email?

  • 0

    @Patrick you should be able to just send in a new email to your support@ address with the same syntax as usual

  • 0

    Ok, this worked to create a new ticket. One question I have is, if I specify a requester email, will it automatically send that person an email about the ticket (even if the email is not currently a user)?

  • 0

    @Patrick if Zendesk can't find anyone associated with an email you specify, Zendesk should create a new user automatically for you. It tries to be a little clever by taking anything before the @ in the email address and using that as the user's name.

  • 0

    Right, ok. But can Zendesk send the user an email when the ticket is created? I'm guessing not since it is assuming the user posted it, but in this case they didn't, we did on their behalf. I notice that as soon as our support team updates the ticket the user gets the notice though.

  • 0

    @Patrick that's entirely dependent on the triggers and notifications you've set up under Manage > Triggers and Notification

    If you're having trouble setting these up, do email support@zendesk.com and they'll be able to help you specifically within your account (and they're a bit faster than I am!).

  • 0

    I send test email to support email address from my email account with this body:

    #status open

    #group Other

    #type Question

    #requester my_customer_mail @gmail.com

    Hello there


    And ticket is created in Zendesk panel but it's requester field is not 'my_customer_mail @gmail.com' as I specified in #requester -  it's my email address. The same with #group - it assigns to default 'Support' group but not to "Other" group (group "Other" is present in my Zendesk aacount)

  • 0

    Thank you. Do you think this method for creating tickets will continue to be supported vs. the REST API?

  • 0

    I tried updating a bunch of tickets simultaneously by putting them all in the To line, but it seems like only one of them worked.  Is there any way to do batch updates with the email interface?

  • 0

    @Aron: Unfortunately that's not possible, sorry!

    @Patrick, Vitaly: I'll look into what's going on with new tickets in regards to requesters and groups. We want similar behavior to the web UI for consistency, so this is a bug.

    @Patrick: Support for this will certainly be continued - in fact this is the second version of the Mail API.

  • 0

    @Jake, Vitaly: Isn't Vitaly's issue a matter of not including blank lines between each command?  That seems to be what the syntax requires.

  • 0


    2 little additions that I think would make a big difference:

    #delete - same as "Delete ticket" in web app

    #spam - same as "Mark as spam and suspend requester" in web app

  • 0


    Does this functionality work with light agents as well?  Thanks.

  • 0

    @Eugene: There should be no reason it wouldn't, but Zendesk will ignore anything that light agents don't have permission to do (such as assigning to themselves, making a public comment, etc).

  • 0

    I am trying to set tags this way but they are ignored. Do you have tags be already defined in previous tickets? Is there a way to create new tags this way?

  • 0

    I think there's a bug in tag parsing. If any of the tags was not entered in the system before, the mail parser will discard all the other tags as well!

  • 0

    @Roman: I'll create a ticket for you

  • 0

    Can we please have access to custom fields, since as you say, this should be similar to UI functionality. Perhaps it would be;

    #custom_field_id value

    _or _

    _#_custom_field_name value

    I think using only the id will make for easier implementation, but I can imagine other users getting a taste for using custom fields and wanting to use the name also. The trouble with the name is that you need to accommodate stuff like "Calls made to lead (where applicable)".

    Similar to native fields, invalid values will be ignored.

  • 0

    Also cc would be good (without having to cc the actual email), ie,

    cc user@zendesk.com

  • 0

    I agree it would be an awesome feature to be able to change values for custom fields through the mail API. I have a custom field that I require to be set before the ticket can be closed, so at the moment my techs can't close tickets via email. I'm testing some work arounds but wanted to make known the desire to have this as a feature if possible.

  • 0

    Is there anyway a macro can be assigned when forwarding an email to zendesk?

  • 1

    Are there plans to add a due date command into the mix? I assume it could look something like

    #due 10/05/12

    Most of my ticket types are tasks, so having to go into the ticket to add a due date is an extra step at this point.

  • 0

    Updating Tickets via the Mail API by using the Subject Line Ticket No.


    Just to clarify for people using the Mail API. It is not possible to update existing tickets with the Mail API when sending a 'fresh' email, only responses to Zendesk via email will execute the Mail API commands on existing tickets. The reason for this is because the API does not identify the ticket via the subject line of the email. The ticket is identified by the reply email formulated with a hash ID.


    As @ Ben Schutz mentioned below, you are able to use the mail API in new tickets from new or forwarded emails (e.g emailing support@[your-subdomain].zendesk.com with a ticket that does not currently have an ID or exists within Zendesk).


  • 0

    ^ If that is the case, this forum entry needs to be rewritten and the graphics changed. As it is, the diagrams are misleading: it looks as though you can update a ticket from a freshly composed e-mail, when you cannot. 

  • 0

    @Jesse Burghiemer: I know how frustrating this is as I too was initially confused by this. I will be pushing to update the article fully and making this clear within the content itself along with the screenshot. I've added in the comment above just as an intermediary step towards republishing this post. 

  • 0

    @Ben Reyes: I think your first comment raises some confusion. While this is in the context of updating existing tickets, "only responses to Zendesk via email will execute the Mail API commands" could be construed as a blanket statement suggesting that you can't use the mail API even when creating new tickets from new or forwarded emails, which you can.

    Just in case anyone was confused.

Powered by Zendesk