Email API
The Email API provides endpoints that enable you to receive and send email messages using REST.
Users must have the email_api_send role to send email.
Remarque :
You might get errors if you do not have read/write access to the Email [sys_email]
table.
Email - GET /now/email/{id}
Returns the email details for the specified email record.
URL format
Versioned URL: /api/now/{api_version}/email/{id}
Remarque :
Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| id | Sys_id of the email for which to return details. Data type: String Table: Email [sys_email] |
| Name | Description |
|---|---|
| sysparm_fields | Comma-separated list of fields to return in the response. Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supported types: application/json or application/xml.
Default: application/json |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 403 | Indicates the record is not found or the requesting user does not have access to the record. Verify the user has the proper role and access permissions. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Element | Description |
|---|---|
| bcc | List of the email addresses of the blind copied recipients of the email
message. Maps to the blind_copied field. Data type: Array |
| cc | List of the email addresses of the copied recipients for the email message.
Maps to the copied field. Data type: Array |
| headers | Name-value pairs of the headers associated with the message and their
values. Data type: Object |
| html | HTML-enabled body of the email message. Maps to the body field. Data type: String |
| id | Sys_id of the email record. Data type: String |
| importance | Importance of the email message. Maps to the importance field. Data type: String |
| state | Processing state of the email message. Indicates whether the system scheduled jobs have processed the email message. Possible include:
Data type: String |
| subject | Subject of the email message. Maps to the subject field. Data type: String |
| text | Text-only body of the email message. Maps to the body_text field. Data type: String |
| to | List of the email addresses of the direct recipients of the email message. Maps
to the recipients field. Data type: Array |
| type | Current state of the email message as incoming or outgoing mail. Possible values:
Data type: String |
Sample cURL request
curl "http://instance.servicenow.com/api/now/email/06e095427f0022007f005212bdfa91b3" \
--request GET \
--header "Accept:application/json" \
--user "user-name":"password"
{
"result" : {
"headers" : {
"X-ServiceNow-SysEmail-Version" : "2",
"X-ServiceNow-Source" : "Notification-24e34b54c61122aa0108c1b7a33697cf"
},
"cc" : [
""
],
"type" : "send-ready",
"html" : "<html><head></head><body><div><p><font size=\"5\" color=\"#808080\" face=\"helvetica\"><strong>Incident has been closed.</strong></font></p></div>\n\t\t<div><p><font size=\"4\" color=\"#808080\" face=\"helvetica\"><strong>Summary details</strong></font></p><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">Closed by: System Administrator</font></p><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">Closed notes: Fixed</font></p></div>\n\t\t<div><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">You can view all the details of the incident by following the link below:</font></p><font face=\"helvetica\"><a href=\"incident.do?sys_id=e8e875b0c0a80164009dc852b4d677d5&sysparm_stack=incident_list.do?sysparm_query=active=true\" style=\"background-color: #278efc;border: 1px solid #0368d4;color: #ffffff;font-size: 16px;font-family: Helvetica, Arial, sans-serif;text-decoration: none; border-radius: 3px;-webkit-border-radius: 3px;-moz-border-radius: 3px;display: inline-block;padding: 5px;\">Take me to the Incident</a></font><br /><br /><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">Thank you.</font></p></div><div> </div><div style=\"display:inline\">Ref:MSG0000006</div></body></html>",
"bcc" : [
""
],
"subject" : "Your incident INC0000005 has been closed",
"to" : [
"alejandro.mascall@example.com"
],
"state" : "ready",
"id" : "06e095427f0022007f005212bdfa91b3",
"importance" : "",
"text" : ""
}
}Email - POST /now/email
Creates an email record using the passed information.
URL format
Versioned URL: /api/now/{api_version}/email
Remarque :
Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| None |
| Element | Description |
|---|---|
| bcc | List of the email addresses of the blind copied recipients of the email
message. Maps to the blind_copied field. Remarque :
You can only specify
up to 100 addresses in this field. Data type: Array |
| cc | List of the email addresses of the copied recipients for the email message.
Maps to the copied field. Remarque :
You can only specify up to 100
addresses in this field. Data type: Array |
| headers | Name-value pairs of the headers associated with the message and their
values. Data type: Object |
| html | HTML-enabled body of the email message. Maps to the body field. Data type: String |
| importance | Importance of the email message. Maps to the importance field. Data type: String |
| subject | Subject of the email message. Maps to the subject field. Data type: String |
| table_name | Name of the table to save the email. Use this parameter to associate an email
message to a particular related record elsewhere in the system. Remarque :
This parameter
also requires specifying the table_record_id
parameter. Data type: String |
| table_record_id | Target-related record to which the email applies. Use this parameter to
associate an email message to a particular related record elsewhere in the
system. Remarque :
This parameter also requires specifying the
table_name parameter. Data type: String |
| text | Text-only body of the email message. Maps to the body_text field. Data type: String |
| to | Required. List of the email addresses of the direct recipients for the email
message. Maps to the recipients field. Remarque :
You can only specify
up to 100 addresses in this field. Data type: Array |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supported types: application/json or application/xml.
Default: application/json |
| Content-Type | Data format of the request body. Supported types: application/json or application/xml.
Default: application/json |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 403 | Requesting user does not have access to the record. Verify that the user has the proper role and access permissions. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Element | Description |
|---|---|
| href | Link to the email record as an Email API GET request. Data type: String |
| id | Sys_id of the Email record. Data type: String |
| links | List of links to the Email record. Data type: Array |
| rel | Type of link listed in the href parameter. Possible
values:
Data type: String |
Sample cURL request
curl "http://instance.servicenow.com/api/now/email" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user 'username':'password'\
--data "{
\"to\": [
\"User1 <user1@example.com>\",
\"User2 <user2@example.com>\"
],
\"cc\": [
\"User3 <user3@example.com>\",
\"User4 <user4@example.com>\"
],
\"bcc\": [
\"User5 <user5@example.com>\",
\"User6 <user6@example.com>\"
],
\"subject\": \"Hello There\",
\"text\": \"Test Message\",
\"html\": \"<b>Test Message</b>\",
\"table_name\": \"incident\",
\"table_record_id\": \"136b2140bd0312004d7d1371f1abbdb6\",
\"headers\": {
\"X-Custom\": \"header\"
}
}"{
"result": {
"id": "b963219a44b02200964f63773cd6adfc",
"links": [
{
"rel": "self",
"href": "/now/v1/email/b963219a44b02200964f63773cd6adfc"
},
{
"rel": "status",
"href": "/now/v1/email/b963219a44b02200964f63773cd6adfc?sysparm_fields=id,type,state,error"
}
]
}
}