Using the Mail API to update 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


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 “” 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


  • 0

    Can this be done for the #cc email address?
    We get clients reporting issues, but wish to add the Sales account manager by CC

  • 0

    Hi Andrew,

    Unfortunately the #CC command is not yet available for the Mail API, only the commands above are the ones present at the moment. That does seem like an interesting feature, would it be possible if you can post in on our Product Feedback here:

  • 0

    Hi All, perhaps I missed it. I have been skimming through the email channel articles but I am not certain if the fw: and re: issue has been addressed. We recently implemented the email channel through our technical support group boxes. Many people use these boxes to carry on conversations about an issue between the dealers, internal as well as external customers. We end up with multiple tickets about the same issue. This seems to be due to the re: when replies are made and fw: when email s are forwarded. Outside of manually merging these conversations, is there anyway to streamline this by stripping off the re: and fw: prefix to the title of the emails when they come into our Zendesk? Clear as mud?

  • 0

    I'm having an issue whereby the #requester command works in the sandbox environment, but not the production one. The designated requester is a light agent user, configured the same in both environments. I have copied/pasted the source email from the production environment -- which didn't have the intended effect -- into an email I sent to the sandbox support environment, and the requester was correctly updated. Any ideas on what may have caused this behavior?

  • 0

    +1 for #appendtags - this would make the functionality actually useful. Default behavior of purging all existing tags is contrary to logic seeing tags are a major functionality linchpin for ticket workflow.

  • 0

    This is exactly what I was looking for as our team has many shared inboxes and this lets me simultaneously respond and create a ticket when it's support-related.

    +1 for custom fields (as I have mandatory custom fields)

    +1 for #take short code for assignee (although #assignee my_email is fine)

  • 0


    Here's a crazy idea. If your mail client supports auto correct, you can set up a short cut for '#assignee my_email' and other mail commands.

    In Outlook, it is under File>Options>Spelling and Auto Correct>Auto Correct Options.

    Might save you some time and some typos ;)

  • 1


    Not a bad workaround. I just set up text expansions for the whole thing:

    for example, "#zdforp" becomes

    #assignee my_email


    I'm a fan of TextExpander, but I think there are free alternatives. OS X's native text replacer is a bit unreliable in my experience.

  • 0

    @Kevin Hill - Add c.c.'s to the ticket using email reply by just entering the email address in the message's c.c. field. No #command in the body is necessary. I agree that it would be nice if we could also do this by #command in the API as well.

  • 1

    I have raised a feature request via the support desk, but would like to add it here for further exposure.

    I would like to see the addition of a Mail API command that either substitutes the ticket number for something like #ticket, or to replace it with some pre-defined text (which would also include the ticket number).

    Use Case: We wish to proactively provide support, raising tickets on behalf of a customer based on an event (such as an automated crash response). As part of the first ticket, we want to provide a place where customers can upload a large file to, way beyond something that can be handled as an attachment. To this end, we offer our customers a portal, and the uploads are associated with the ticket number such that they can click on a link and go straight to the correct page. This URL takes the format of:


    At the moment, I have to raise the ticket, wait for Zendesk to reply with the ticket reference, then send a second email with the link, which is a bit rubbish.

    Of course, the replacement would need to be in the BODY of the email. So we would have something like:

    Hi User,

    Please upload to:



    You already have some ability here as of course Zendesk assigns a ticket reference and adds it to the response email. This will perhaps somehow stand on the back of that feature.



  • 0

    I back Chris Sweeney's request and will go hunt that down and say so there.

    We would use it when creating an RMA ticket for a customer based on a phone call and not a technical support ticket. We use the ticket number as the RMA number and currently have to figure out what the next ticket number will be (and race to claim it) or do things in two steps. Being able to indicate in the body of the email that I want you to stick the new ticket number there would help a lot.

  • 0

    I should also say this request above would be useful in follow up emails, not just initial email. Again, we point our customers to a URL based on the ticket number, The only way I have to do this today it to paste preformatted text, but keep manually updating the URL, which has inevitably led to human error in the past.

  • 0

    Further to the above (WRT adding URLs/Text containing the ticket number), you guys already have the idea of Marcos. We have a simple Marco that inserts, something like:

    Please upload the file to{{}}

    The problem with this is it doesn't work on NEW tickets (ones that we raise on behalf of our customers).

    So, firstly this field needs to be able to be processed during the ticket creation submission stage, rather than text entry stage, AND we need a way to reference that Macro via the Mail API.

  • 3

    Is there any progress on the #cc command?

    this was raised as the very first comment in this post back in June 2012, over 4 years ago! It has been repeated multiple times since. A quick search found suggestions posted in the Product Feedback forum over 7 years ago!!!!

    Perhaps this is something that needs to be implemented......

  • 2

    +1 on the #cc command

  • 1

    How do I unsubscribe from this thread? Important feature requests or features gets no response from ZenDesk, so what's the point?

  • 0

    We have automated systems that send out notifications to zendesk with requests that need to be actioned.


    We were wondering if there will be an improvement to add #requester when non agent sends that?


    This would be useful!

  • 0

    I've been toying around with the Mail API for adding internal notes. We often "escalate" tickets to the Sales group who works strictly from email. By default, I have all replies from email set to PRIVATE (as Sales usually starts off with internal chatter about how to prioritize the lead). 

    I was hoping they could use #internal to chatter amongst themselves and #public when they are ready for the requestor (end user) to see it. However, when the first #public reply is sent, all of the previous internal chatter is added to the body of the email (this was meant to be for our team's eyes only i.e. internal notes). 

    Any ideas for how to make this work? I'd love for Sales to be able to talk amongst themselves before replying, but it makes this feature pretty useless if sending a public reply makes all previous internal notes visible to the customer. Any suggestions?

    I'm also open to an entirely different workflow but the idea is that Sales likes to chat amongst themselves and they like to work from email (not the Zendesk dashboard). 

    See test ticket below. As soon as the public reply was sent, it added the private note to the body (visible to end user): 


    This is a screenshot of the email (what it looks like to the end user). They can see the private note!  "Let's call him ASAP!" 

  • 0


    Maybe the issue is in your "Notify requester of comment update" trigger?

    I use this in the Email body:

    {% for comment in ticket.comments limit:1 offset:0 %}
    {% for attachment in comment.attachments %}
    {% endfor %}
    {% endfor %}

    Note the limit:1

    This makes sure only the most recent comment is sent (in this case your public reply). I do this to make everything seem as email-like as possible, rather than helpdesk-like

  • 0

    Juliet - 

    This is clearly an issue, but I'm not sure what's causing it. I'm submitting your comment to our Support team to investigate it privately.

  • 2

    Maybe would be possible to update custom ticket fields?

  • 0

    Could #requester uses the external ID ?

  • 0

    Hi Jean-Francois!  It would not be possible to use external ID for #requester.  You can use an email address or user ID of an exiting user.

  • 0

    Hi Zen Support,

    We have been trying to figure out a way to best serve our customer through pro-active support tickets, and there are some things thet Zen simply doesn't support, but comes close in other areas.

    The workflow is something like this

    1. ACR from the customer software is reported to our ACR server, and generate an internal issue for tracking
    2. We then raise ticket on behalf of the customer using the Email API, inserting relevant information commands such as:

      #group Incident reports
      #requester ****@****
      Some info about the ACR

    3. An automated trigger has been setup to forward a properly formatted email to the customer indicating where to upload more information such as below. This has to come now as we have no idea what the ticket number will be before we create the ticket, and the upload URL uses the ticket number to cross link the information.{{}}

    4. In this way, the customer does NOT get the first email when we raise the ticket on their behalf, but receive a nicely formatted auto response. The problem is that as we reply, they see the first entry, which is not what we are after.
    5. Lastly we cross link the ticket and ACR issue. 

    As such, I though it would be a simple task of adding the #note property to the first email from us, thus:

    #group Incident reports
    #requester ****@****
    Some info about the ACR
    Private link to GIT repository....

    By doing this, it means we "should" be able to add additional private commentary in the first email, the customer get the auto-response, but the ticket then carries on. Problem is, this doesn't work. The initial email remains public.

    The alternative method is for Zendesk to support Mail API commends in the initial email that could then be substituted when processed and turned into a ticket (also mentioned in my post a while ago above), however this seem more ticket.

    The addition of the #note in the first email would seem to be a simple win here.



  • 0

    Hey Chris!

    I think I understand what you're getting at here, but please let me know if I'm off the mark. What I'm reading is that you don't want your end-user to see the very first comment on the ticket that you've created on their behalf.

    The good news is that we just went live with a functionality that allows you to create a ticket with the very first comment as an internal note. You might need to tweak your workflow a little bit to make sure that notifications are sent out to your requesters properly, but I think this will solve your problem.

    You can find more information about that here: 

    Let me know if I misunderstood anything!

Please sign in to leave a comment.

Powered by Zendesk