Using the Mail API to update ticket properties from your inbox

<body>
<div class="article-banners">
<div id="docs-wmp-link">
<a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a>
</div>
<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>
<div class="article-banner" id="support_all">
<table>
<tbody>
<tr>
<td>
<strong>Support</strong>
</td>
<td>Team, Professional, or Enterprise</td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="docs-ai-summary">
<p id="docs-ai-summary-toggle">Verified AI summary <span id="up-triangle">◀</span><span id="down-triangle">▼</span></p>
<p id="docs-ai-summary-content">Use the Mail API to update ticket properties directly from your inbox by adding commands to your email. This feature is available for agents and allows you to set ticket status, assignee, priority, and more. Commands must be in plain text at the top of your email. Invalid commands are ignored, and existing tickets can only be updated by replying to their email notifications.</p>
</div>
<div class="body">
<p class="p">The Mail API allows you to set ticket properties by adding commands to the body of an email
response to a notification or an email creating a new ticket. Only agents
can use the Mail API. If these commands are used by light agents or end
users, Zendesk ignores them.</p>
<p class="p">Here's an example of an agent setting the status and assignee of a ticket in a
reply to an email notification: </p>
<p class="p"><img class="image img-screenshot" height="221" id="topic-1__image_zhg_t5b_4g" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/mail_api_example_1b.png" width="338"></p>
<p class="p">An agent can also use the commands in a new email sent to their support address.
This kind of email creates a new ticket. </p>
<p class="p">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. </p>
<p class="p">Tickets that are created or updated with the Mail API are handled through the
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408888639258" target="_blank">email channel</a>.</p>
<div class="p">
<div class="note" id="topic-1__note_vxb_kbq_4fc">
<span class="notetitle">Note:</span> 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. </div>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_t11_zsb_4g">
<h2 class="title topictitle2" id="ariaid-title2">Syntax</h2>
<div class="body">
<p class="p">The Mail API simply scans the top of your email for the list of commands
you want to perform.</p>
<p class="p">The commands must be in plain text, not HTML, and follow the following
pattern: </p>
<p class="p"><code class="ph codeph">#command value</code>
</p>
<p class="p">If, for example, you want to set the status of a ticket, use this
command: </p>
<p class="p"><code class="ph codeph">#status solved</code>
</p>
<p class="p">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: </p>
<p class="p"><code class="ph codeph">#status solved </code></p>
<p class="p"><code class="ph codeph">#assignee jake@zendesk.com</code>
</p>
<p class="p">Enter the body of your email after the block of commands.</p>
<div class="note">
<span class="notetitle">Note:</span> There should only be one space between your command and value. </div>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_jtp_dtb_4g">
<h2 class="title topictitle2" id="ariaid-title3">Command reference</h2>
<div class="body">
<p class="p">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 <em class="ph i">short
commands</em>, one-word commands for regularly used commands
that don't need a value. For example, you can use the short command
<code class="ph codeph">#solved</code> instead of <code class="ph codeph">#status
solved</code>.</p>
<div class="note">
<span class="notetitle">Note:</span> Using custom field names as commands is not supported.</div>
<div class="p">
<div class="tablenoborder">
<table border="1" cellpadding="4" cellspacing="0" class="table" frame="border" id="topic_jtp_dtb_4g__table_5qg_b5b_4g" rules="all" summary="">
<colgroup>
<col style="width:121px">
<col style="width:100%">
</colgroup>
<thead class="thead" style="text-align:left;">
<tr class="row">
<th class="entry nocellnorowborder" id="d87e139" style="vertical-align:top;">Command</th>
<th class="entry cell-norowborder" id="d87e142" style="vertical-align:top;">Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;">
<code class="ph codeph">#status</code> </td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">
<p class="p">Valid values are open, pending, and
solved. Note: #assignee must be set in order to
set a ticket to solved. </p>
<p class="p">Short syntax:
<code class="ph codeph">#open #pending
#solved</code></p>
<strong class="ph b">Note</strong>: The
<code class="ph codeph">#solved</code> command only works for
tickets that don't have required fields that the
agent must fill out before the ticket can be
solved.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;"><code class="ph codeph">#requester </code></td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">
<p class="p">Sets the requester of the ticket. This can be
the user's ID in your account or their email
address. If they don't already exist in your
account, Zendesk will create it for you.</p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;">
<code class="ph codeph">#group </code>
</td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">Assigns the ticket to a group. Valid values
are the name of the group or the ID of a group.
<p class="p">This command is especially useful for forwarded
emails. When an agent forwards an email to
Zendesk, by default the resultant ticket is
either unassigned or assigned to the agent's
default group. (See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836514202-Passing-an-email-to-your-support-address#topic_ym4_2ng_3k" target="_blank">Passing an email to
your support address</a>.) Agents can use this
command to automatically assign the forwarded
ticket to the specified group instead.
</p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;"><code class="ph codeph">#assignee</code></td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">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).<p class="p">Using this command
automatically makes you a collaborator (cc) on the
ticket.</p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;"><code class="ph codeph">#priority </code></td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">
<p class="p">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) </p>
<p class="p">Short syntax: <code class="ph codeph">#low #normal #high
#urgent</code>
</p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;"><code class="ph codeph">#type</code></td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">
<p class="p">Valid values are incident, question, task, and
problem. </p>
<p class="p">Short syntax: <code class="ph codeph">#incident #question #task
#problem</code></p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d87e139" style="vertical-align:top;">
<p class="p"><code class="ph codeph">#tags </code></p>
</td>
<td class="entry cell-norowborder" headers="d87e142" style="vertical-align:top;">
<p class="p">Sets any tag on the ticket, which can
be separated by spaces or commas. </p>
<p class="p"><strong class="ph b">Note</strong>: Setting the tags removes all
previously set tags on that ticket.</p>
</td>
</tr>
<tr class="row">
<td class="entry row-nocellborder" headers="d87e139" style="vertical-align:top;">
<code class="ph codeph">#public</code> </td>
<td class="entry cellrowborder" headers="d87e142" style="vertical-align:top;">
<p class="p">Sets a comment update on a ticket to public.
Only usable when updating a ticket. </p>
<p class="p">The default value for public tickets is true,
meaning that the requester will see anything else
you put in the body of the email. The default
value for private tickets, such as tickets created
by light agents, is false.</p>
<p class="p">Short syntax: <code class="ph codeph">#note</code> (makes
future comments from that agent private for that
ticket, unless reversed by #public on each
individual comment)</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_lb5_vtb_4g">
<h2 class="title topictitle2" id="ariaid-title4">Invalid commands</h2>
<div class="body">
<p class="p">If you enter any invalid commands or values, Zendesk ignores them. </p>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested1" id="topic_4pj_wgc_vg">
<h2 class="title topictitle2" id="ariaid-title5">Example</h2>
<div class="body">
<p class="p">In this example, the agent uses all the commands. </p>
<p class="p"><img class="image img-screenshot" height="280" id="topic_4pj_wgc_vg__image_qyn_ygc_vg" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/mail_api_example_2.png" width="341"></p>
<p class="p">The email does the following to ticket #178: </p>
<div class="p">
<ul class="ul" id="topic_4pj_wgc_vg__ul_dyn_ygc_vg">
<li class="li">Sets the status to open</li>
<li class="li">Sets the group to “Support” and the assignee to the
agent with “jake@zendesk.com” as their email
address</li>
<li class="li">Sets the priority to “normal”</li>
<li class="li">Sets the type to “question”</li>
<li class="li">Sets the tags to “help” and “api”</li>
<li class="li">Sets the visibility of the comment to “private”</li>
<li class="li">Adds a new comment with “Hello world!” to the ticket,
which combined with the above command, will not be
visible to the requester.</li>
</ul>
</div>
</div>
</div>
<script id="ai-summary-script">
//<![CDATA[
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//]]>
</script>
</body>