Goal: attachments that arrive intact and render correctly.
Step 1. Read the file and base64-encode it into the content property. SendGrid expects the encoded string, not raw bytes.
Step 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.
Step 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.
Step 4. Test to seed addresses and open the attachment on multiple clients. Encoding bugs show up as corrupt files, not API errors.
Verify: seeds receive intact files with correct names and types, and no 413s in the send logs. Pitfall: double-encoding the content (encoding an already-base64 string) is the most common corrupt-attachment cause.