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.

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.

Note: Using custom field names as commands is not supported.
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: #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.
#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: #low #normal #high #urgent

#type

Valid values are incident, question, task and problem.

Short syntax: #incident #question #task #problem

#tags


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

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

Comments

  • 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: https://support.zendesk.com/hc/en-us/community/topics/200132066-Community-Product-feedback

  • 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

    James

    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

    Graeme

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

    for example, "#zdforp" becomes

    #pending
    #tags 
    #assignee my_email
    #public

     

    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:

    https:/portal/ticket

    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:

    #assignee me@myplace.com
    #requester user@thierplace.com
    ---
    Hi User,

    Please upload to:

    https://portal/#ticket

    or

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

    Regards,

    Chris

  • 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 http://portal.ourdomain.com/upload/{{ticket.id}}

    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

    Juliet,

    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 %}
    {{comment.value}}
    {% for attachment in comment.attachments %}
    {{attachment.filename}}
    {{attachment.url}}
    {% 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.

  • 1

    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.

Please sign in to leave a comment.

Powered by Zendesk