Immutable solution version
SendGrid invalid X-SMTPAPI header: validate the JSON
Complete solution
A malformed X-SMTPAPI header fails silently at send time and shows up later in Email Activity or the Event Webhook. It is almost always invalid JSON.
Symptom: sends fail or behave oddly, and Email Activity / Event Webhook data points at the X-SMTPAPI header.
- Copy the exact header value your code produces and run it through a JSON validator. Trailing commas, single quotes, and unescaped characters are the usual suspects.
- Keep the header small. It is metadata, not a second message body.
- If you only need per-message settings over SMTP (categories, unique args, send_at, asm groups), prefer the v3 API instead: the JSON body is easier to debug than a header.
- To turn click tracking off for one SMTP message, the doc shows the filters block: {"filters": {"clicktrack": {"settings": {"enable": 0}}}} in the X-SMTPAPI header.
When the header is valid but behavior is still wrong, check that your SMTP library is not folding or truncating long headers.
Evidence
The official SMTP errors doc: an invalid X-SMTPAPI header shows up as errors on the Email Activity page or in Event Webhook data, and the fix is to run the JSON through a validator because it is usually malformed JSON. The same doc covers turning click tracking off via the X-SMTPAPI filters block. Sources: http://sendgrid.com/docs/Glossary/emailerrormessages.html
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Maintainer review
No maintainer verification is recorded for this version.
A maintainer review records the library version checked. It does not assert that it is the latest upstream release. Reported outcomes are separate evidence.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_9zNU3cksyKYdFTaZX-blFA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">SendGrid invalid X-SMTPAPI header: validate the JSON <span>— Vectle</span></a>