SendGrid attachment workflow: encoding, types, size

TL;DR: Attach files via the SendGrid API with the content property holding a base64 string (SendGrid expects the encoded string, not raw bytes), type set to the MIME type, filename to the name recipients see, and disposition to attachment for downloads. Keep the total message size under the content-too-large limit. Test to seed addresses: encoding bugs show up as corrupt files, not API errors.

Steps:

1. Read the file and base64-encode it into the content property. Success: the property holds an ASCII base64 string, not raw bytes.
2. Set type to the MIME type (application/pdf for PDFs), filename to the name recipients see, and disposition to attachment for downloads. Use inline with a content_id only for images referenced from the HTML body. Success: the attachment block has all four fields.
3. Keep the total message size in check: attachments plus body count toward the content-too-large limit. Compress or link large files instead of attaching them. Success: no 413s in the send logs.
4. Test to seed addresses and open the attachment on multiple clients. Success: seeds receive intact files with correct names and types.

When to use: sending attachments through the SendGrid v3 API.

When not to use: SMTP sends (different attachment mechanism), template or dynamic-content rendering problems, or delivery/reputation issues.

Compatibility: SendGrid v3 Mail Send API, any language.

Variants:

• sendgrid api attachment base64
• sendgrid attachment corrupt
• sendgrid content too large attachment

Root cause: most attachment failures are encoding or field mistakes, and they are silent at the API level. The send succeeds; the file arrives corrupt. That is why the verification step opens the file instead of trusting the 202.

Edge cases:

• Pitfall: double-encoding the content (encoding an already-base64 string) is the most common corrupt-attachment cause. Encode exactly once.
• Inline disposition needs a matching content_id referenced from the HTML body, or the image shows as a broken reference instead of inline.

The mail send reference: attachments need content as a base64 string plus type, filename, disposition, and content_id properties. Total message size counts toward the 413 content-too-large limit. Sources: https://docs.sendgrid.com/api-reference/mail-send/mail-send