When using the X-SMTPAPI header, you may find from time to time that you have an invalid smtpapi header. You may see these errors in your Email Activity or Event Notification log. When you have these errors it is important to check your email for the details of the invalid smtpapi header.

Example Email Activity:

Example Event Notification log using our EventKit:

Example invalid smtpapi header email:

A message was received from this address by our systems that had errors in the smtpapi header, and cannot be processed. The error detected was: Error decoding SMTP API header: , or ] expected while parsing array, at character offset 50 (before “:{“%name%”:[“Ben”,”J…”) If you require assistance in working with the SMTP API, please contact us at support@sendgrid.com

In this email you can find all the details you need to begin troubleshooting your invalid smtpapi header. In our example we can see the error happened “at character offset 50 (before “:{“%name%”:[“Ben”,”J…”)”. If we review the X-SMTPAPI header that was sent we should find what caused the issue.

Example invalid smtpapi header:

{“to”:[“ben@sendgrid.com”,”joe@sendgrid.com”,”sub”:{“%name%”:[“Ben”,”Joe”],”%role%”:[“%sellerSection%”,”%buyerSection%”]},”section”:{“%sellerSection%”:”Seller information for: %name%”,”%buyerSection%”:”Buyer information for: %name%”},”category”:[“Orders”],”unique_args”:{“orderNumber”:”12345”,”eventID”:”6789”}}

Looking at the content of the header before “character offset 50” we can focus our attention and find the issue:


Looking at this we can see that the closing of the “to” section did not happen. The “to” section should have been:


To either prevent or troubleshoot issues like this you can run your JSON through our SMTP API Header Validator. Additionally, JSONLint or JSONLintCompressor can be used to help as well.

If you still need help, please use the links below.