{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":509,"path":"api-reference/rest-apis/email-api.md","title":"Email API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Email API\n\nThe Email API provides endpoints that enable you to receive and send email messages using REST.\n\nUsers must have the email\\_api\\_send role to send email.\n\n**Note:** You might get errors if you do not have read/write access to the Email \\[sys\\_email\\] table.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Email - GET /now/email/\\{id\\}\n\nReturns the email details for the specified email record.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/email/{id}`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr><tr><td>\n\nid\n\n</td><td>\n\nSys\\_id of the email for which to return details.Data type: String\n\nTable: Email \\[sys\\_email\\]\n\n</td></tr></tbody>\n</table><table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsysparm\\_fields\n\n</td><td>\n\nComma-separated list of fields to return in the response.Data type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|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.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nElement\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nbcc\n\n</td><td>\n\nList of the email addresses of the blind copied recipients of the email message. Maps to the blind\\_copied field.Data type: Array\n\n</td></tr><tr><td>\n\ncc\n\n</td><td>\n\nList of the email addresses of the copied recipients for the email message. Maps to the copied field.Data type: Array\n\n</td></tr><tr><td>\n\nheaders\n\n</td><td>\n\nName-value pairs of the headers associated with the message and their values.Data type: Object\n\n</td></tr><tr><td>\n\nhtml\n\n</td><td>\n\nHTML-enabled body of the email message. Maps to the body field.Data type: String\n\n</td></tr><tr><td>\n\nid\n\n</td><td>\n\nSys\\_id of the email record.Data type: String\n\n</td></tr><tr><td>\n\nimportance\n\n</td><td>\n\nImportance of the email message. Maps to the importance field.Data type: String\n\n</td></tr><tr><td>\n\nstate\n\n</td><td>\n\nProcessing state of the email message. Indicates whether the system scheduled jobs have processed the email message. Possible include:\n\n-   error\n-   ignored\n-   processed\n-   ready\n\nData type: String\n\n</td></tr><tr><td>\n\nsubject\n\n</td><td>\n\nSubject of the email message. Maps to the subject field.Data type: String\n\n</td></tr><tr><td>\n\ntext\n\n</td><td>\n\nText-only body of the email message. Maps to the body\\_text field.Data type: String\n\n</td></tr><tr><td>\n\nto\n\n</td><td>\n\nList of the email addresses of the direct recipients of the email message. Maps to the recipients field.Data type: Array\n\n</td></tr><tr><td>\n\ntype\n\n</td><td>\n\nCurrent state of the email message as incoming or outgoing mail. Possible values:\n\n-   received\n-   received-ignored\n-   send-failed\n-   send-ignored\n-   send-ready\n-   sent\n\nData type: String\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"http://instance.servicenow.com/api/now/email/06e095427f0022007f005212bdfa91b3\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"user-name\":\"password\"\n\n```\n\n```\n{\n  \"result\" : {\n    \"headers\" : {\n      \"X-ServiceNow-SysEmail-Version\" : \"2\",\n      \"X-ServiceNow-Source\" : \"Notification-24e34b54c61122aa0108c1b7a33697cf\"\n    },\n    \"cc\" : [\n      \"\"\n    ],\n    \"type\" : \"send-ready\",\n    \"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>\",\n    \"bcc\" : [\n      \"\"\n    ],\n    \"subject\" : \"Your incident INC0000005 has been closed\",\n    \"to\" : [\n      \"alejandro.mascall@example.com\"\n    ],\n    \"state\" : \"ready\",\n    \"id\" : \"06e095427f0022007f005212bdfa91b3\",\n    \"importance\" : \"\",\n    \"text\" : \"\"\n  }\n}\n```\n\n## Email - POST /now/email\n\nCreates an email record using the passed information.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/email`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nElement\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nbcc\n\n</td><td>\n\nList 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.\n\n Data type: Array\n\n</td></tr><tr><td>\n\ncc\n\n</td><td>\n\nList 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.\n\n Data type: Array\n\n</td></tr><tr><td>\n\nheaders\n\n</td><td>\n\nName-value pairs of the headers associated with the message and their values.Data type: Object\n\n</td></tr><tr><td>\n\nhtml\n\n</td><td>\n\nHTML-enabled body of the email message. Maps to the body field.Data type: String\n\n</td></tr><tr><td>\n\nimportance\n\n</td><td>\n\nImportance of the email message. Maps to the importance field.Data type: String\n\n</td></tr><tr><td>\n\nsubject\n\n</td><td>\n\nSubject of the email message. Maps to the subject field.Data type: String\n\n</td></tr><tr><td>\n\ntable\\_name\n\n</td><td>\n\nName 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.\n\n Data type: String\n\n</td></tr><tr><td>\n\ntable\\_record\\_id\n\n</td><td>\n\nTarget-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.\n\n Data type: String\n\n</td></tr><tr><td>\n\ntext\n\n</td><td>\n\nText-only body of the email message. Maps to the body\\_text field.Data type: String\n\n</td></tr><tr><td>\n\nto\n\n</td><td>\n\nRequired. 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.\n\n Data type: Array\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|403|Requesting user does not have access to the record. Verify that the user has the proper role and access permissions.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nElement\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nhref\n\n</td><td>\n\nLink to the email record as an Email API GET request.Data type: String\n\n</td></tr><tr><td>\n\nid\n\n</td><td>\n\nSys\\_id of the Email record.Data type: String\n\n</td></tr><tr><td>\n\nlinks\n\n</td><td>\n\nList of links to the Email record.Data type: Array\n\n</td></tr><tr><td>\n\nrel\n\n</td><td>\n\nType of link listed in the **href** parameter.Possible values:\n\n-   self: The Email API GET request for the Email record.\n-   status: The Email API GET request for the Email record showing only the id, type, state, and error fields.\n\n Data type: String\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"http://instance.servicenow.com/api/now/email\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user 'username':'password'\\\n--data \"{\n  \\\"to\\\": [\n    \\\"User1 <user1@example.com>\\\",\n    \\\"User2 <user2@example.com>\\\"\n  ],\n  \\\"cc\\\": [\n    \\\"User3 <user3@example.com>\\\",\n    \\\"User4 <user4@example.com>\\\"\n  ],\n  \\\"bcc\\\": [\n    \\\"User5 <user5@example.com>\\\",\n    \\\"User6 <user6@example.com>\\\"\n  ],\n  \\\"subject\\\": \\\"Hello There\\\",\n  \\\"text\\\": \\\"Test Message\\\",\n  \\\"html\\\": \\\"<b>Test Message</b>\\\",\n  \\\"table_name\\\": \\\"incident\\\",\n  \\\"table_record_id\\\": \\\"136b2140bd0312004d7d1371f1abbdb6\\\",\n  \\\"headers\\\": {\n    \\\"X-Custom\\\": \\\"header\\\"\n  }\n}\"\n```\n\n```\n{\n \"result\": {\n   \"id\": \"b963219a44b02200964f63773cd6adfc\",\n   \"links\": [\n     {\n       \"rel\": \"self\",\n       \"href\": \"/now/v1/email/b963219a44b02200964f63773cd6adfc\"\n     },\n     {\n       \"rel\": \"status\",\n       \"href\": \"/now/v1/email/b963219a44b02200964f63773cd6adfc?sysparm_fields=id,type,state,error\"\n     }\n   ]\n }\n}\n```\n\n"}}