Failed requests will always return an error response, including a response code, a message explaining the reason for the error, and a link to any relevant documentation that may help you troubleshoot the problem.

Response Code Reason Description
2xx 2xx responses indicate a successful request The request that you made is valid and successful.
200 OK Your message is valid, but it is not queued to be delivered. †
202 ACCEPTED Your message is both valid, and queued to be delivered.
4xx 4xx responses indicate an error with the request There was a problem with your request.
400 BAD REQUEST
401 UNAUTHORIZED You do not have authorization to make the request.
403 FORBIDDEN
404 NOT FOUND The resource you tried to locate could not be found or does not exist.
405 METHOD NOT ALLOWED
413 PAYLOAD TOO LARGE The JSON payload you have included in your request is too large.
415 UNSUPPORTED MEDIA TYPE
429 TOO MANY REQUESTS The number of requests you have made exceeds SendGrid’s rate limitations
5xx 5xx responses indicate an error made by SendGrid An error occurred when SendGrid attempted to processes it.
500 SERVER UNAVAILABLE An error occurred on a SendGrid server.
503 SERVICE NOT AVAILABLE The SendGrid v3 Web API is not available.

† Sandbox mode only.

Following is a complete list of the possible parameter level errors that you may receive when making a request to the v3 Mail Send endpoint. Each error will include the field that caused the error (e.g. “personalizations” or “personalizations.to”), a brief message explaining the cause of the error, and a link to the error in the table below. Here you will find links to relevant documentation for each error.

Table of Contents

Personalizations Errors

personalizations

Error Code Error Message Details
400
The personalization block is limited to 1000 personalizations per API request. You have provided X personalizations. Please consider splitting this into multiple requests and resending your request.
The v3 Mail Send endpoint is only capable of processing 1000 individual personalizations objects per request. If you need to send your email to more than 1000 different recipients, we recommend that you simply make more than once call. For more information about the personalizations array, and how you can use it to define who you would like you send your email to, and how you would like your email to be processed, please visit our Classroom.
You must have at least one personalization.
Every email you send must have at least one recipient email address included. Recipients are defined in the personalizations array. For more information on how to use personalizations to define who you want to send your email to, please visit our Classroom.
There is a limit of 1000 total recipients (to + cc + bcc) per request.
The combined, total number of email recipients may never exceed 1000. This includes recipients defined within the to, cc, and bcc parameters. For more information on how you may specify your recipients, please visit our Classroom.
Each "to" object must at least have an email address and may also contain a name. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
For every recipient that you define within a personalizations.to parameter, you must include one, valid email address. You are not required to include a name.
Each unique email address in the personalizations array should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Classroom.
The to parameter is required for all personalization objects.
For every single object that you include within the personalizations array, you must include at least one to email object with a valid email address. For more information on how you may specify your recipients, please visit our Classroom.

personalizations.bcc

Error Code Error Message Details
400
The bcc array, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
For every blind carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Classroom.
Each recipient object must at least have an email address and may also contain a name. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
Every recipient that you define within the personalizations.cc array must be in the form of an email object including one, valid email address. You are not required to include a name.
Each unique email address in the personalization block should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Classroom.

personalizations.cc

Error Code Error Message Details
400
The cc array, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
For every carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Classroom.
Each recipient object must at least have an email address and may also contain a name. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
Every recipient that you define within the personalizations.cc array must be in the form of an email object including one, valid email address. You are not required to include a name.
Each unique email address in the personalization block should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Classroom.

personalizations.custom_args

Error Code Error Message Details
400
All values of custom arguments object must be strings
Custom argument values must always be strings. You cannot define arrays, integers, or booleans as custom argument values. Click here more information about how to use custom arguments.
custom_args cannot be empty.
If you include the custom_args parameter, you must include at least one value. If you do not want to use any custom arguments, simply omit the custom_arg param from your request. Click here more information about how to use custom arguments.
The combined size of both global and personalization custom arguments may not exceed 10,000 bytes per personalization.
personalizations[x].custom_args will be merged with message level custom_args, overriding any conflicting keys. The combined total size of the resulting custom arguments, after merging, for each personalization may not exceed 10,000 bytes. Click here more information about how to use custom arguments.

personalizations.headers

Error Code Error Message Details
400
All values of the headers object must be strings.
The object type of every header that you include must be a string. You cannot include headers that are integers, booleans, or arrays.
The headers cannot contain duplicate keys.
You may not include the same header more than once.
Header keys cannot contain non-ASCII characters or empty spaces.
When defining the headers that you would like to use, you must make sure that the string contains only ASCII characters.
Header cannot be one of the reserved keys.
Some header keys are reserved. You may not include any of the following reserved keys: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.

personalizations.send_at

Error Code Error Message Details
400
The send_at parameter is expecting a Unix timestamp as an integer. We will send immediately if you include a send_at timestamp that is in the past.
send_at accepts a unix timestamp representing when you want your email to be sent from SendGrid. If you want the email to be sent at the time of your API request, simply omit the send_at parameter.
Scheduling more than 72 hours in advance is forbidden.
The send_at parameter allows you to schedule your email to be sent up to 72 hours in advance, but due to our constraints, we cannot schedule emails more than 72 hours in the future. For more information on scheduling parameters, please see our API Reference.

personalizations.subject

Error Code Error Message Details
400
The subject of your email must be a string at least one character in length.
You are required to include a subject for every email you send, and you may not include an empty subject. The minimum length of your subject is one character.
The subject is required. You can get around this requirement if you use a template with a subject defined.
Every email must have a subject. This can be accomplished 3 ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.

personalizations.substitutions

Error Code Error Message Details
400
The substitution values must be an object of key/value pairs, where the values are all strings.
Substitutions must always follow the pattern "substitution_tag": "value to substitute". The value to substitute for the "substitution_tag" must always be a string.
You are limited to 10,000 substitutions.
You may not make more than 10,000 substitutions per request. Substitutions will apply to the content of your email, in addition to the subject and reply_to parameters

personalizations.to

Error Code Error Message Details
400
The to array must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
Every email you send must have at least one, valid recipient email address included. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Classroom.

ASM Errors

asm.group_id

Error Code Error Message Details
400
The ASM group ID must be an integer.
Suppression Groups, or unsubscribe groups, are a great way to record which emails your recipients want to receive. Including the asm.group_id in your request allows you to group your email with other, similar sends. However, these group IDs are always generated as integers, and so you must ensure that asm.group_id is defined as an integer. For more information please read our Unsubscribe Groups documentation.
The ASM group ID must be a valid Group ID on your account. You provided [YOUR ASM GROUP ID].

asm.groups_to_display

Error Code Error Message Details
400
The ASM Group IDs to display must be an array of integers.
All ASM groups to display must be valid ASM groups IDs on your account. You provided {invalid IDs}.
There is a limit of 25 unsubscribe groups that can be displayed to a user at a time.

Attachment Errors

attachments.content

Error Code Error Message Details
400
The attachment content must be base64 encoded.
The attachment content must be a string at least one character in length.

attachments.content_id

Error Code Error Message Details
400
The content ID of your attachment must be a string. You provided [YOUR CONTENT ID].
The content_id is a unique id that you specify for the attachment. This is used when the disposition is set to "inline" and the attachment is an image, allowing the file to be displayed within the body of your email. For example, <img src="cid:ii_139db99fdb5c3704"></img>
The content ID of your attachment cannot contain CRLF characters.
When defining your content_id, you may not include the characters ;, ,, n, or r.

attachments.disposition

Error Code Error Message Details
400
The disposition of your attachment can be either "inline" or "attachment". You provided [YOUR DISPOSITION].
The content-disposition of your attachment defines how you would like the attachment to be displayed. For example, "inline" results in the attached file being displayed automatically within the message while "attachment" results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file). attachments.disposition always defaults to "attachment". Can be either "attachment" or "inline".

attachments.filename

Error Code Error Message Details
400
The filename of your attachment must be a string.
The filename of your attachment cannot contain CRLF characters.
When defining the filename of your attachment, you may not include the characters ;, ,, n, or r.
filename is required.
You must always include a filename for your attachment.

attachments.type

Error Code Error Message Details
400
The attachment type must be a string and at least one character in length.
The type cannot contain ‘;’, or CRLF characters.
When defining the type of your attachment content, you may not include the characters ;, ,, n, or r.

Batch ID Errors

batch_id

Error Code Error Message Details
400
The batch_id must be a string.
Batch IDs are always generated as strings, so when you choose to include a batch ID in your send, you must make sure that batch_id is defined as a string. For more information about batch IDs, and how you can use them to group sends together, please visit our API Reference.

Categories Errors

categories

Error Code Error Message Details
400
There is a limit of 10 categories for each email that is sent. You provided X categories.
For more information on how you can use categories to organize your email analytics, please visit our User Guide.
Categories must be an array of strings.
Every object that you include within the categories array must be a string. For more information on how you can use categories to organize your email analytics, please visit our User Guide.
Each category must not be longer than 255 characters. [YOUR CATEGORY] exceeds this limit
he maximum length of a category is 255 characters. For more information on how you can use categories to organize your email analytics, please visit our User Guide.
The categories must be a unique list, and you have included [YOUR CATEGORY] more than once.
You cannot include the same category more than once within the categories array. For more information on how you can use categories to organize your email analytics, please visit our User Guide.
Categories can not contain non-ASCII characters.
Each category name must only be comprised of ASCII characters. For more information on how you can use categories to organize your email analytics, please visit our User Guide.

Content Errors

content

Error Code Error Message Details
400
The content param is required unless you are using a transactional template and have defined a template_ID.
You may not send an email without the content parameter unless you are using a transactional template. This is to prevent you from sending an empty email to your recipients.
There must be at least one defined content block. We typically suggest both text/plain and text/html blocks are included, but only one block is required.
You must specify at least one content type and value for every email you send. We recommend that you include both text/plain and text/html to ensure that all of your recipients are able to read your email, but you are only required to define one type of content.

content.type

Error Code Error Message Details
400
A content type is required, this tells email clients how to display the email.
You must always specify the MIME type of content you are including in your email, and if you are including the text/plain type, it must be specified first, followed by text/html, and then any other MIME types you would like to specify.
The content value must be a string at least one character in length.
You may not send an email with no content.
Your content type must be a string with length of at least one character.
The content of your email must always be contained within a string when you make your request.
Cannot contain ‘;’, or CRLF characters.
When defining the type of your content, you may not include the characters ;, ,, n, or r.

content.value

Error Code Error Message Details
400
A content value is required, this is the content of the email you are sending.
We do not allow you to send an empty email to your recipients. You must always include a value for your content.
The content value must be a string at least one character in length.
We do not allow you to send an empty email to your recipients. Even if you include the content.value parameter, it must include at least one character.
Following RFC 1341, section 7.2, if either text/html or text/plain are to be sent in your email: text/plain needs to be first, followed by text/html, followed by any other content.
The order in which you specify the MIME types of your content must always be text/plain first, if you choose to include it, followed by text/html, and then any other MIME types you wish to include.

Encoding Errors

Encoding

Error Code Error Message Details
415
Invalid UTF8 in request
Your payload must be encoded in UTF-8. This includes any attachments.

From Address Errors

from

Error Code Error Message Details
400
The from object must at least have an email parameter with a valid email address and may also contain a name parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
While every from parameter must include a valid email address, you are not required to include a name.
The from object must be provided for every email send. It is an object that requires the email parameter, but may also contain a name parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
You are required to provide a from address whenever you send an email through SendGrid. This is used for authentication purposes and helps to build a positive sending reputation with your recipients' ISPs. You are not required to include a name within the from parameter.

Headers Errors

headers

Error Code Error Message Details
400
The header values must be strings.
The object type of every header that you include must be a string. You cannot include headers that are integers, booleans, or arrays.
The headers cannot contain duplicate keys.
You may not include the same header more than once.
Header keys cannot contain non-ASCII characters and empty spaces.
When defining the headers that you would like to use, you must make sure that the string contains only ASCII characters.
Header can not be one of the reserved keys.
Some header keys are reserved. You may not include any of the following reserved headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.

IP Pool Errors

ip_pool_name

Error Code Error Message Details
400
The name of your IP pool must be a string.
The IP Pool name must be a valid pool name for your account. You provided [YOUR IP POOL NAME].

Reply To Errors

reply_to

Error Code Error Message Details
400
The reply_to object, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
For every carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Classroom.

Sections Errors

sections

Error Code Error Message Details
400
The section values must be strings.
The values of your sections parameter will be substituted into the content of your email. We will only perform substitutions using strings, so please make sure that your section values are always defined as strings.

Send At Errors

send_at

Error Code Error Message Details
400
The send_at parameter is expecting a Unix timestamp as an integer. We will send immediately if you include a send_at timestamp that is in the past.
send_at accepts a unix timestamp representing when you want your email to be sent from SendGrid. If you want the email to be sent at the time of your API request, simply omit the send_at parameter.
Scheduling more than 72 hours in advance is forbidden.
The send_at parameter allows you to schedule your email to be sent up to 72 hours in advance, but due to our constraints, we cannot schedule emails more than 72 hours in the future. For more information on scheduling parameters, please see our API Reference.

Subject Line Errors

subject

Error Code Error Message Details
400
The subject of your email must be a string at least one character in length.
You are required to include a subject for every email you send, and you may not include an empty subject. The minimum length of your subject is one character.
The subject is required. You can get around this requirement if you use a template with a subject defined or if every personalization has a subject defined.
Every email must have a subject. This can be accomplished 3 ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.

Template Errors

template_id

Error Code Error Message Details
400
The template ID must be a string, you provided [YOUR TEMPLATE ID].
Template IDs are always strings.
The Template ID must be a valid template id for your account. You provided [YOUR TEMPLATE ID].
We do not allow you to send an empty email, so in the event that the only content of your email is contained within your template, we want to make sure that the included template exists, and is valid.
Must be a valid template.
We do not allow you to send an empty email, so in the event that the only content of your email is contained within your template, we want to make sure that the included template exists, and is valid.

Mail Settings Errors

mail_settings.bcc.email

Error Code Error Message Details
400
The bcc email recipient object must at least have an email address and may also contain a name. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}
You must include a recipient object when using the bcc mail setting.

mail_settings.bcc.enable

Error Code Error Message Details
400
The bcc enable param should be a boolean value.

mail_settings.bypass_list_management.enable

Error Code Error Message Details
400
The bypass list management enable param should be a boolean value.

mail_settings.footer.enable

Error Code Error Message Details
400
The footer enable param should be a boolean value.

mail_settings.footer.html

Error Code Error Message Details
400
The text/html version of your footer should be a string.

mail_settings.footer.text

Error Code Error Message Details
400
The text/plain version of your footer should be a string.

mail_settings.sandbox_mode.enable

Error Code Error Message Details
400
The sandbox mode enable param should be a boolean value.

mail_settings.spam_check.enable

Error Code Error Message Details
400
The spam check enable param should be a boolean value.

mail_settings.spam_check.post_to_url

Error Code Error Message Details
400
The spam check url must be a string.
You must include the url to post to when using the spam check mail setting.
The `post_to_url` parameter must start with `http://` or `https://`.

mail_settings.spam_check.threshold

Error Code Error Message Details
400
The spam check threshold is between 1 and 10, with the lower numbers being the most strict filtering.
You must include the spam check threshold when using the spam check mail setting.

Tracking Settings Errors

tracking_settings.click_tracking.enable

Error Code Error Message Details
400
The click tracking enable param should be a boolean value.

tracking_settings.click_tracking.enable_text

Error Code Error Message Details
400
The click tracking enable text must be a boolean value.

tracking_settings.ganalytics.enable

Error Code Error Message Details
400
The Google Analytics enable param must be a boolean value.

tracking_settings.ganalytics.utm_campaign

Error Code Error Message Details
400
The Google Analytics utm_campaign must be a string value.

tracking_settings.ganalytics.utm_content

Error Code Error Message Details
400
The Google Analytics utm_content must be a string value.

tracking_settings.ganalytics.utm_medium

Error Code Error Message Details
400
The Google Analytics utm_medium must be a string value.

tracking_settings.ganalytics.utm_source

Error Code Error Message Details
400
The Google Analytics utm_source must be a string value.

tracking_settings.ganalytics.utm_term

Error Code Error Message Details
400
The Google Analytics utm_term must be a string value.

tracking_settings.open_tracking.enable

Error Code Error Message Details
400
The open tracking enable param should be a boolean value.

tracking_settings.open_tracking.substitution_tag

Error Code Error Message Details
400
The open tracking substitution tag must be a string.

tracking_settings.subscription_tracking.enable

Error Code Error Message Details
400
The subscription tracking enable param should be a boolean value.

tracking_settings.subscription_tracking.html

Error Code Error Message Details
400
The subscription tracking unsubscribe content for text/html messages must be a string.

tracking_settings.subscription_tracking.substitution_tag

Error Code Error Message Details
400
The subscription tracking substitution tag must be a string value.

tracking_settings.subscription_tracking.text

Error Code Error Message Details
400
The subscription tracking unsubscribe content for text/plain messages must be a string.