Updating ticket properties from your inbox

Updating ticket properties from your inbox

The mail API allows you to set ticket properties by adding commands to the body of an email response to a Zendesk 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 the support address of their Zendesk account. This kind of email creates a new ticket.

When Zendesk 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 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 Zendesk 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.
CommandDescription

#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

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

  • Avatar
    Kevin Hill

    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

  • Avatar
    John Gannon

    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

  • Avatar
    Pete P

    Does the curly bracket API format still work as well?

  • Avatar
    Jake Holman

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

  • Avatar
    Patrick

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

  • Avatar
    Jake Holman

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

  • Avatar
    Patrick

    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)?

  • Avatar
    Jake Holman

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

  • Avatar
    Patrick

    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.

  • Avatar
    Jake Holman

    @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!).

  • Avatar
    Vitaly Pushkar

    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)

  • Avatar
    Patrick

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

  • Avatar
    Aron Griffis

    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?

  • Avatar
    Jake Holman

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

  • Avatar
    Bob Sherer

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

  • Avatar
    David Goss

    Jake

    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

  • Avatar
    Eugene Orr

    Hi,

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

  • Avatar
    Jake Holman

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

  • Avatar
    Roman R

    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?

  • Avatar
    Roman R

    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!

  • Avatar
    Jake Holman

    @Roman: I'll create a ticket for you

  • Avatar
    Ben Schutz

    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.

  • Avatar
    Ben Schutz

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

    cc user@zendesk.com

  • Avatar
    Lucas Alton

    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.

  • Avatar
    Chris Mollan

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

  • Avatar
    Ryan Adams

    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.

  • Avatar
    Ben Reyes

    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.

    <Edit>

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

    </Edit>

  • Avatar
    Jesse Burghiemer

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

  • Avatar
    Ben Reyes

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

  • Avatar
    Ben Schutz

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

Please sign in to leave a comment.