Errors

Menu

Errors

Below is a list of errors you may get while interacting with the SendGrid API. The error code for each error is 400.

Personalizations Errors

personalizations

Error Message Details
The personalization block is limited to 1000 personalizations per API request. You have provided [n] 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 make more than one 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 Personalizations documentation.
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 Personalizations documentation.
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 Personalizations documentation.
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 Personalizations documentation.
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 Personalizations documentation.

personalizations.bcc

Error Message Details
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 Personalizations documentation.
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 Personalizations documentation.

personalizations.cc

Error Message Details
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 Personalizations documentation.
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 Personalizations documentation.

personalizations.custom_args

Error Message Details
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. See our Unique Arguments documentation for 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. See our Unique Arguments documentation for more information about how to use custom arguments.
The combined size of both global and personalization custom arguments may not exceed 50,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 50,000 bytes. See our Unique Arguments documentation for more information about how to use custom arguments.

personalizations.headers

Error Message Details
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 Message Details
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, 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 Message Details
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 three 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 Message Details
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 50,000 bytes worth of substitutions per request. Substitutions will apply to the content of your email, in addition to the subject and reply_to parameters.

personalizations.to

Error Message Details
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 Personalizations documentation.

ASM Errors

asm.group_id

Error Message Details
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, 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 Message Details
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.contents

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

attachments.content_id

Error Message Details
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, orr`.

attachments.disposition

Error Message Details
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 Message Details
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 Message Details
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

Error Message Details
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. You must first generate a batch_id via the API; it will not be automatically generated for you. See the Create a Batch ID API reference to generate a batch_id. For more information about batch IDs, and how you can use them to group sends together, please visit our API Reference.

Categories Errors

Error Message Details
There is a limit of 10 categories for each email that is sent. You provided [n] categories. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
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 Categories documentation.
Each category must not be longer than 255 characters. [YOUR CATEGORY] exceeds this limit. The 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 Categories documentation.
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 Categories documentation.
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 Categories documentation.

Content Errors

content

Error Message Details
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 Message Details
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 Message Details
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

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

From Address Errors

Error Message Details
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 fromparameter.

Headers Errors

Error Message Details
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 keys: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.

IP Pool Errors

Error Message Details
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

Error Message Details
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 Personalizations documentation.

Sections Errors

Error Message Details
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

Error Message Details
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, 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

Error Message Details
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 three ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.

Template Errors

Error Message Details
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 Message Details
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 Message Details
The bcc enable param should be a boolean value.

mail_settings.bypass_list_management.enable

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

mail_settings.footer.enable

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

mail_settings.footer.html

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

mail_settings.footer.text

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

mail_settings.sandbox_mode.enable

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

mail_settings.spam_check.enable

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

mail_settings.spam_check.post_to_url

Error Message Details
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 Message Details
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 Message Details
The click tracking enable param should be a boolean value.

tracking_settings.click_tracking.enable_text

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

tracking_settings.ganalytics.enable

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

tracking_settings.ganalytics.utm_campaign

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

tracking_settings.ganalytics.utm_content

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

tracking_settings.ganalytics.utm_medium

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

tracking_settings.ganalytics.utm_source

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

tracking_settings.ganalytics.utm_term

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

tracking_settings.open_tracking.enable

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

tracking_settings.open_tracking.substitution_tag

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

tracking_settings.subscription_tracking.enable

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

tracking_settings.subscription_tracking.html

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

tracking_settings.subscription_tracking.substitution_tag

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

tracking_settings.subscription_tracking.text

Error Message Details
The subscription tracking unsubscribe content for text/plain messages must be a string.
Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Need help? Talk to Support
Protected by reCAPTCHA – PrivacyTerms
Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif