---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Email API

# Email API {#ariaid-title1}

* Release version: Yokohama
* 
* Updated August 11, 2026
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

The Email API provides endpoints that enable you to receive and send email messages using REST.{#email-api__release-notes-feature-description}
Users must have the email_api_send role to send email.  
Note:  
You might get errors if you do not have read/write access to the Email \[sys_email\] table.

## Email - GET /now/email/{id} {#ariaid-title2}

Returns the email details for the specified email record.

### URL format {#email-GET__section_kdx_pzs_cmb}

Versioned URL:
/api/now/{api_version}/email/{id}  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#email-GET__entry__2}{#email-GET__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. 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\] |
[Table 1. Path parameters]

{#email-GET__entry__8}

| Name | Description |
|-|-|
| sysparm_fields | Comma-separated list of fields to return in the response. Data type: String |
[Table 2. Query parameters]

{#email-GET__entry__12}

| Name | Description |
|-|-|
| None |   |
[Table 3. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#email-GET__entry__16}{#email-GET__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 4. Request headers]

{#email-GET__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#email-GET__entry__24}{#email-GET__entry-200-status-code}{#email-GET__entry-401-status-code}{#email-GET__entry-500-status-code}

| 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. |
[Table 6. Status codes]

### Response body parameters (JSON or XML)

{#email-GET__entry__34}

| 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: * error * ignored * processed * ready {#email-GET__ul_l1x_dp2_zw} 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: * received * received-ignored * send-failed * send-ignored * send-ready * sent {#email-GET__ul_z3k_n42_zw} 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&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 - POST /now/email {#ariaid-title3}

Creates an email record using the passed information.

### URL format {#email-POST__section_urw_jpt_cmb}

Versioned URL:
/api/now/{api_version}/email  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#email-POST__entry__2}{#email-POST__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 7. Path parameters]

{#email-POST__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 8. Query parameters]

{#email-POST__entry__10}

| Element | Description |
|-|-|
| bcc | List of the email addresses of 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. Data type: Array |
| cc | List of the email addresses of the copied recipients for the email message. Maps to the copied field. Note: 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. Note: 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. Note: 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. Note: You can only specify up to 100 addresses in this field. Data type: Array |
[Table 9. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#email-POST__entry__32}{#email-POST__accept-RESTAPI}{#email-POST__content_type-RESTAPI}

| 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 |
[Table 10. Request headers]

{#email-POST__entry__38}

| Header | Description |
|-|-|
| None |   |
[Table 11. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#email-POST__entry__42}{#email-POST__entry-200-status-code}{#email-POST__entry-400-status-code}{#email-POST__entry-401-status-code}{#email-POST__entry-500-status-code}

| 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. |
[Table 12. Status codes]

### Response body parameters (JSON or XML)

{#email-POST__entry__54}

| 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: * 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. {#email-POST__ul_gwp_rrt_cmb} 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"
         }
       ]
     }
    }