Use the Email Notifications API to find out what happened after an email was sent to its recipients. For example, you can use the API to determine if an outbound email was actually delivered and, if not, understand why based on the delivery status codes returned by the email service providers upon request; For more information about email notifications, see Understanding email delivery failures in the Zendesk Agent Workspace in Zendesk help.

Delivery Status Reference

Every recipient from an email notification includes a delivery status information, with "id", "name", "code", and "message" properties. This provides more information directly from the email service providers during the email delivery transaction.

The following table contains for possible values for delivery status:

IdNameSMTP Status CodeDescription
0NONE0No delivery failure responses received
1UNRECOGNIZED_INTERNAL_ERROR1Email failed to deliver. Try sending again
2UNRECOGNIZED_EXTERNAL_ERROR2Email failed to deliver. Try sending again
3NET_SMTP_SYNTAX_ERROR3Email failed to deliver. Try sending again
4ACTIVE_RECORD_NOT_FOUND_ERROR4Email failed to deliver. Try sending again
6SYNTAX_ERROR_COMMAND_UNRECOGNIZED500Email failed to deliver. Status code: 500. The SMTP command used was not recognized due to a syntax error, or is not supported by the given protocol or SMTP server implementation
7AUTHENTICATION_EXCHANGE_LINE_TOO_LONG500 5.5.6Email failed to deliver. Status code: 500 5.5.6. Authentication exchange line is too long
8SYNTAX_ERROR_IN_ARGUMENTS501Recipient server rejected email. Status code: 501. Syntax error in parameters or arguments
9CANNOT_BASE64_DECODE_CLIENT_RESPONSES501 5.5.2Recipient server rejected email. Status code: 501 5.5.2. Cannot base64-decode client responses
10CLIENT_INITIATED_AUTHENTICATION_EXCHANGE501 5.7.0Recipient server rejected email. Status code: 501 5.7.0. Client initiated authentication exchange
11COMMAND_NOT_IMPLEMENTED502Email failed to deliver. Status code: 502. Command not implemented
12BAD_SEQUENCE_OF_COMMANDS503Email failed to deliver. Status code: 503. Bad sequence of commands
13COMMAND_PARAMETER_NOT_IMPLEMENTED504Email failed to deliver. Status code: 504. Command parameter is not implemented
14UNRECOGNIZED_AUTHENTICATION_TYPE504 5.5.4Email failed to deliver. Status code: 504 5.5.4. Unrecognized authentication type
15SMTP_SERVICE_NOT_AVAILABLE505Recipient server rejected email. Status code: 505. SMTP service not available
16BAD_EMAIL_ADDRESS510Recipient server rejected email. Status code: 510. Email address rejected due to bad email address. Email does not exist or was misspelled. Check the recipient's email for typos
17RECIPIENT_EMAIL_ADDRESS_INVALID511Recipient server rejected email. Status code: 511. Recipient's email address is incorrect or invalid
18SENDER_EMAIL_ADDRESS_BLOCKED_OR_SUSPENDED517Email failed to deliver.
19IP_AND_SPF_RECORD_DO_NOT_MATCH520Email failed to deliver. Status code: 520. IP and SPF record do not match
20SERVER_DOES_NOT_ACCEPT_MAIL521Recipient server rejected email. Status code: 521. The server does not accept mail
21SENDER_IP_ON_BLOCKLIST522Email failed to deliver
22ENCRYPTION_NEEDED_OR_EMAIL_TOO_LARGE523Recipient server rejected email. Status code: 523. Encryption needed or email size exceeds the recipient's email server limits. These limits are set by the email server and only allow emails of a specific size to be accepted
23DISABLED_RECIPIENT_ADDRESS525Recipient server rejected email. Status code: 525. Email address disabled. The recipient address is disabled
24AUTHENTICATION_REQUIRED530Email failed to deliver. Status code: 530. Authentication is required
26AUTHENTICATION_CREDENTIALS_INVALID534 5.7.8Email failed to deliver. Status code: 534 5.7.8. The authentication credentials are invalid
25AUTHENTICATION_MECHANISM_WEAK534 5.7.9Email failed to deliver. Status code: 534 5.7.9. The authentication mechanism is too weak
27ENCRYPTION_REQUIRED538 5.7.11Email failed to deliver. Status code: 538 5.7.11. Encryption is required for the requested authentication mechanism
28RECIPIENT_ADDRESS_REJECTED_INACTIVE540Recipient server rejected email. Status code: 540. The recipient address was rejected
29MAILBOX_UNAVAILABLE550Recipient server rejected email. Status code: 550. Requested action not taken: mailbox unavailable (for example, the mailbox was not found or unavailable, no access is permitted, or a command was rejected for policy reasons)
38MAILBOX_INVALID550 5.0.0Recipient server rejected email. Status code: 550 5.0.0. Invalid mailbox; recommend rechecking email address and domain. Invalid mailbox. Re-check the email address and domain
39USER_DOES_NOT_EXIST550 5.1.1Recipient server rejected email. Status code: 550 5.1.1. User does not exist; recommend checking for typos. User does not exist. Check for typos in the email address
40RECIPIENT_IS_INACTIVE550 5.2.1Recipient server rejected email. Status code: 550 5.2.1. Inactive email address. The email address is inactive
30USER_NOT_LOCAL551Recipient server rejected email. Status code: 551. User not local; please try forward-path
31MAILBOX_FULL552Recipient server rejected email. Status code: 552. Recipient's inbox is full. The recipient's inbox is full
32MAILBOX_NAME_NOT_ALLOWED553Recipient server rejected email. Status code: 553. Requested action not taken: mailbox name not allowed
33TRANSACTION_FAILED554Recipient server rejected email. Status code: 554. Transaction has failed (or, in the case of a connection-opening response, no SMTP service here)
34MESSAGE_TOO_BIG554 5.3.4Recipient server rejected email. Status code: 554 5.3.4. Message too large. Recipient server rejected email. The message is too large
35DOMAIN_DOES_NOT_ACCEPT_MAIL556Recipient server rejected email. Status code: 556. Recipient server rejected email. The domain does not accept email
36MESSAGE_REJECTED_SUSPECTED_SPAM558Recipient server rejected email. Status code: 558. Recipient server rejected email. The message content was rejected due to suspected spam
37RECIPIENT_ADDRESS_REJECTED577Recipient server rejected email. Status code: 577. Recipient server rejected email. The recipient address was rejected. This could be due to an undeliverable address or the user is unknown in the relay recipient table
41RECIPIENT_REJECTED_ADDRESS541Recipient server rejected email. Status code: 541

JSON format

Email Notifications are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
comment_idintegertruefalseThe comment ID associated to this email notification
created_atstringtruefalseWhen this email notification was created
email_idstringtruefalseThe email ID of this email notification
message_idstringtruefalseThe value of the Message-Id header of the email
notification_idintegertruefalseThe notification id of this email notification
recipientsarraytruefalseThe list of recipients associated to this email notification
ticket_idintegertruefalseThe ticket ID associated to this email notification
updated_atstringtruefalseWhen this email notification was last updated
urlstringtruefalseThe API url of this email notification

Example

{  "comment_id": 7824075373565,  "created_at": "2024-02-21T23:13:07Z",  "email_id": "01HQ6Z3DE28F34XBFCYH0SRM95",  "message_id": "<[email protected]>",  "notification_id": 7824075373693,  "recipients": [    {      "delivery_status": {        "code": "530 5.7.0",        "id": 24,        "message": "Email failed to deliver. Status code: 530",        "name": "authentication_required"      },      "email_address": "[email protected]",      "user_id": 7612709251581    }  ],  "ticket_id": 623,  "updated_at": "2024-02-21T23:13:07Z",  "url": "https://example.zendesk.com/api/v2/email_notifications/7824075373693.json"}

List Email Notifications

  • GET /api/v2/email_notifications

Allowed For

  • Agents

Filters

  • By notification: api/v2/email_notifications.json?filter[notification_id]=7824075373693
  • By comment: api/v2/email_notifications.json?filter[comment_id]=7824075373565
  • By ticket: api/v2/email_notifications.json?filter[ticket_id]=623

Pagination

By default, a maximum of 100 email notifications are included per page. Use cursor-based pagination parameters (page[after] and page[before]) to navigate the records (can't be used together in the same request). See Pagination for more details.

  • Limit items per-page: api/v2/email_notifications.json?page[size]=25
  • Retrieve next page: api/v2/email_notifications.json?page[size]=25&page[after]=xxx
  • Retrieve previous page: api/v2/email_notifications.json?page[size]=25&page[before]=yyy

The values xxx and yyy are placeholder values that represent cursors.

Sorting

By default, email notifications are sorted by creation time (newest first). The query parameter is not supported for this endpoint.

  • By creation time (oldest first): api/v2/email_notifications.json?sort=created_at
  • By creation time (newest first): api/v2/email_notifications.json?sort=-created_at
  • By modification time (recently updated first): api/v2/email_notifications.json?sort=updated_at
  • By modification time (recently updated last): api/v2/email_notifications.json?sort=-updated_at

Parameters

NameTypeInRequiredDescription
filterintegerQueryfalseFilters the email notifications by ticket, comment, or notification id. Allowed values are "ticket_id", "comment_id", or "notification_id".
per_pageintegerQueryfalseThe number of records to return per page
sortstringQueryfalseThe field to sort the list. Possible values are "created_at", "updated_at" (ascending order) or "-created_at", "-updated_at" (descending order)

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/email_notifications.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/email_notifications?filter=&per_page=&sort=updated_at"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/email_notifications")		.newBuilder()		.addQueryParameter("filter", "")		.addQueryParameter("per_page", "")		.addQueryParameter("sort", "updated_at");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/email_notifications',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'filter': '',    'per_page': '',    'sort': 'updated_at',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/email_notifications?filter=&per_page=&sort=updated_at"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/email_notifications")uri.query = URI.encode_www_form("filter": "", "per_page": "", "sort": "updated_at")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "email_notifications": [    {      "comment_id": 7824075373565,      "created_at": "2024-02-21T23:13:07Z",      "email_id": "01HQ6Z3DE28F34XBFCYH0SRM95",      "message_id": "<[email protected]>",      "notification_id": 7824075373693,      "recipients": [        {          "delivery_status": {            "code": "530 5.7.0",            "id": 24,            "message": "Email failed to deliver. Status code: 530",            "name": "authentication_required"          },          "email_address": "[email protected]",          "user_id": 7612709251581        }      ],      "ticket_id": 623,      "updated_at": "2024-02-21T23:13:07Z",      "url": "https://example.zendesk.com/api/v2/email_notifications/7824075373693.json"    },    {      "comment_id": 7975134672637,      "created_at": "2024-05-16T20:15:20Z",      "email_id": "01HY1GPZVDQAQK3CKWD3MFPX7Z",      "message_id": "<[email protected]>",      "notification_id": 7975134674301,      "recipients": [        {          "delivery_status": {            "code": "538 5.7.11",            "id": 27,            "message": "Email failed to deliver. Status code: 538 5.7.11",            "name": "encryption_required"          },          "email_address": "[email protected]",          "user_id": 1100021780374        },        {          "delivery_status": {            "code": "200",            "id": 5,            "message": "Email was delivered.",            "name": "delivered"          },          "email_address": "[email protected]",          "user_id": 6020924697213        }      ],      "ticket_id": 626,      "updated_at": "2024-05-16T20:15:20Z",      "url": "https://example.zendesk.com/api/v2/email_notifications/7975134674301.json"    },    {      "comment_id": 7975121425149,      "created_at": "2024-05-16T20:15:58Z",      "email_id": "01HY1GR2T8VKSPZ73TMCWAFWS3",      "message_id": "<[email protected]>",      "notification_id": 7975121425661,      "recipients": [        {          "delivery_status": {            "code": "0",            "id": 0,            "message": "No delivery response has been received.",            "name": "none"          },          "email_address": "[email protected]",          "user_id": 1100021780374        },        {          "delivery_status": {            "code": "501",            "id": 8,            "message": "Recipient server rejected email. Status code: 501",            "name": "syntax_error_in_arguments"          },          "email_address": "[email protected]",          "user_id": 6020924697213        }      ],      "ticket_id": 626,      "updated_at": "2024-05-16T20:15:58Z",      "url": "https://example.zendesk.com/api/v2/email_notifications/7975121425661.json"    }  ]}

Show Email Notification

  • GET /api/v2/email_notifications/{notification_id}

Shows details on an email notification. You can get the value of the notification_id parameter by listing the ticket's outbound emails.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
notification_idintegerPathtrueThe id of the email notification

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/email_notifications/{notification_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/email_notifications/7824075373693"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/email_notifications/7824075373693")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/email_notifications/7824075373693',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/email_notifications/7824075373693"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/email_notifications/7824075373693")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "email_notification": {    "comment_id": 7824075373565,    "created_at": "2024-02-21T23:13:07Z",    "email_id": "01HQ6Z3DE28F34XBFCYH0SRM95",    "message_id": "<[email protected]>",    "notification_id": 7824075373693,    "recipients": [      {        "delivery_status": {          "code": "530 5.7.0",          "id": 24,          "message": "Email failed to deliver. Status code: 530",          "name": "authentication_required"        },        "email_address": "[email protected]",        "user_id": 7612709251581      }    ],    "ticket_id": 623,    "updated_at": "2024-02-21T23:13:07Z",    "url": "https://example.zendesk.com/api/v2/email_notifications/7824075373693.json"  }}

Show Many Email Notifications

  • GET /api/v2/email_notifications/show_many?comment_ids={comment_ids}&ids={ids}&ticket_ids={ticket_ids}

Shows details of many email notifications. Allows you to query by providing a list of notifications, comments, or tickets IDs.

Allowed For

  • Agents

Filters

  • By notification: ?ids=8433702508541,8433348111869
  • By comment: ?comment_ids=8433348111741,8433544226045,8433702508413
  • By ticket: ?ticket_ids=730,723

Parameters

NameTypeInRequiredDescription
comment_idsstringQuerytrueComma-separated list of comment ids
idsstringQuerytrueComma-separated list of notification ids
ticket_idsstringQuerytrueComma-separated list of ticket ids

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/email_notifications/show_many.json?ids={ids} \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/email_notifications/show_many?comment_ids=8433348111741%2C8433544226045%2C8433702508413&ids=8433702508541%2C8433348111869&ticket_ids=35436%2C35437"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/email_notifications/show_many")		.newBuilder()		.addQueryParameter("comment_ids", "8433348111741,8433544226045,8433702508413")		.addQueryParameter("ids", "8433702508541,8433348111869")		.addQueryParameter("ticket_ids", "35436,35437");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/email_notifications/show_many',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'comment_ids': '8433348111741%2C8433544226045%2C8433702508413',    'ids': '8433702508541%2C8433348111869',    'ticket_ids': '35436%2C35437',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/email_notifications/show_many?comment_ids=8433348111741%2C8433544226045%2C8433702508413&ids=8433702508541%2C8433348111869&ticket_ids=35436%2C35437"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/email_notifications/show_many")uri.query = URI.encode_www_form("comment_ids": "8433348111741,8433544226045,8433702508413", "ids": "8433702508541,8433348111869", "ticket_ids": "35436,35437")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "email_notification": {    "comment_id": 7824075373565,    "created_at": "2024-02-21T23:13:07Z",    "email_id": "01HQ6Z3DE28F34XBFCYH0SRM95",    "message_id": "<[email protected]>",    "notification_id": 7824075373693,    "recipients": [      {        "delivery_status": {          "code": "530 5.7.0",          "id": 24,          "message": "Email failed to deliver. Status code: 530",          "name": "authentication_required"        },        "email_address": "[email protected]",        "user_id": 7612709251581      }    ],    "ticket_id": 623,    "updated_at": "2024-02-21T23:13:07Z",    "url": "https://example.zendesk.com/api/v2/email_notifications/7824075373693.json"  }}