Email API

With the Email API you can receive and send email messages using REST.

Security

Users must have the email_api_send role to send email.

Email API - GET /now/email/{sys_id}

This method returns the record details of the specified email record.

URL format

Versioned URL: /api/now/v1/email/{sys_id}

Supported request parameters

Table 1. Parameters
Parameter 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.

Table 2. Request headers
Header Description
None
Table 3. Response headers
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 response codes .

Table 4. Status codes
Status code Description
200 Indicates the request completed successfully. If a valid query returned no results, the response body contains only an empty result array.
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.

Request body

The API accepts these JSON or XML elements in the request body.

Table 5. Elements accepted in the request body
Element Description
None

Response body

The API returns these JSON or XML elements in the response body.

Table 6. Elements returned in the response body
Element Description
headers Array consisting of the email message headers.
cc Array consisting of the copied recipients of the email message. Maps to the copied field.
type The current state of the email message as incoming or outgoing mail. Values include:
  • received
  • received-ignored
  • send-failed
  • send-ignored
  • send-ready
  • sent
html The HTML-enabled body of the email message. Maps to the body field.
bcc Array consisting of the blind copied recipients of the email message. Maps to the blind_copied field.
subject Specifies the subject of the email message. Maps to the subject field.
to Array consisting of the direct recipients of the email message. Maps to the recipients field.
state The processing state of the email message. Indicates whether system scheduled jobs have processed the email message. Values include:
  • error
  • ignored
  • processed
  • ready
id The sys_id of the Email record.
importance The importance of the email message. Maps to the importance field.
text The text-only body of the email message. Maps to the body_text field.

Sample cURL request

curl "http://instance.service-now.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&amp;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>&nbsp;</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" : ""
   }
}

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'http://instance.service-now.com/api/now/email/06e095427f0022007f005212bdfa91b3'

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"application/json","Accept":"application/json"}

# Do the HTTP request
response = requests.get(url, auth=(user, pwd), headers=headers )

# Check for HTTP codes other than 200
if response.status_code != 200:
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
{
   "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&amp;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>&nbsp;</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 API - POST /now/email

This method creates the email record specified in the request body.

URL format

Versioned URL: /api/now/v1/email

Supported request parameters

Table 7. Parameters
Parameter 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.

Table 8. Request headers
Header Description
None
Table 9. Response headers
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 response codes .

Table 10. Status codes
Status code Description
200 Indicates that the request completed successfully.
400 Indicates that there is an error with the request message. The response body contains information about the error.
403 Indicates that the requesting user does not have access to the record. Verify that the user has the proper role and access permissions.
500 Indicates that there is an unexpected or internal error.

Request body

The API accepts these JSON or XML elements in the request body to specify the content of the email message you want to create in the Email [sys_email] table.

Table 11. Elements accepted in the request body
Element Description

to

(Required)

Specifies the direct recipients of the email message. Maps to the recipients field.
Note: You can only specify up to 100 addresses in this field.
cc Specifies the copied recipients of the email message. Maps to the copied field.
Note: You can only specify up to 100 addresses in this field.
bcc Specifies the blind copied recipients of the email message. Maps to the blind_copied field.
Note: You can only specify up to 100 addresses in this field.
subject Specifies the subject of the email message. Maps to the subject field.
text Specifies the text-only body of the email message. Maps to the body_text field.
html Specifies the HTML-enabled body of the email message. Maps to the body field.
importance Specifies the importance of the email message. Maps to the importance field.
table_name Specifies the table of the related record to which the email applies. Use this parameter to associate an email message to a particular related record elsewhere in the system.
Note: This parameter also requires specifying the table_record_id parameter.
table_record_id Specifies the 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.
Note: This parameter also requires specifying the table_name parameter.
headers Specify an array of custom headers you want to include in the email message. Custom headers must begin with an X- prefix. These custom headers are reserved for ServiceNow only and produce a 400 status code error:
  • X-ServiceNow
  • X-Service-Now

Response body

The API returns these JSON or XML elements in the response body to describe the email record created.

Table 12. Response body elements
Element Description
id The sys_id of the Email record.
links Array consisting of links to the Email record.
rel The type of link listed in the href parameter.
  • self: The Email API GET request for the Email record.
  • status: The Email API GET request for the Email record showing only the id, type, state, and error fields.
href Specifies the link to the Email record as an Email API GET request.

Sample cURL request

curl "http://instance.service-now.com/api/now/email" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--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\"
             }
         }" \
--user 'admin':'admin'
{
 "result": {
   "id": "b963219a44b02200964f63773cd6adfc",
   "links": [
     {
       "rel": "self",
       "href": "/now/v1/email/b963219a44b02200964f63773cd6adfc"
     },
     {
       "rel": "status",
       "href": "/now/v1/email/b963219a44b02200964f63773cd6adfc?sysparm_fields=id,type,state,error"
     }
   ]
 }
}

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'http://localhost:8080/api/now/v1/email'

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"application/json","Accept":"application/json"}

# Do the HTTP request
response = requests.post(url, auth=(user, pwd), headers=headers ,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\"
			}
		}")

# Check for HTTP codes other than 200
if response.status_code != 200: 
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
{
 "result": {
   "id": "b963219a44b02200964f63773cd6adfc",
   "links": [
     {
       "rel": "self",
       "href": "/now/v1/email/b963219a44b02200964f63773cd6adfc"
     },
     {
       "rel": "status",
       "href": "/now/v1/email/b963219a44b02200964f63773cd6adfc?sysparm_fields=id,type,state,error"
     }
   ]
 }
}