How to Add Attachments in SendGrid

Attachments can make or break your email campaigns. A proposal without the attached deck, a receipt that never arrives, an onboarding guide that gets lost in transit — these mistakes cost you deals, credibility, and customers.

SendGrid processes over 100 billion emails every month, making it one of the most widely used email delivery platforms in the world. Yet most teams underutilize its attachment functionality or run into avoidable errors that tank deliverability.

This guide covers everything — from the basics of attaching files via the SendGrid dashboard to advanced API-level control — so your attachments land in the inbox every single time.

Why Attachments Matter in Email (and Why They’re Tricky)

Email with attachments gets clicked 38% more often than emails without them, according to research from Campaign Monitor. But attachments also introduce real risks:

• Spam filters flag emails with large or suspicious attachments
• File size limits cause hard bounces when exceeded
• Encoding errors corrupt files before they reach recipients
• Deliverability drops when attachment MIME types are poorly handled

SendGrid gives you precise control over all of these variables — if you know how to use it correctly.

What You Need Before You Start

Before adding any attachment in SendGrid, make sure you have:

• A verified SendGrid account (free or paid)
• A verified sender identity (domain or single sender)
• The file you want to attach, properly formatted
• API key with Mail Send permissions (for API-based sending)

SendGrid supports attachments via three main routes: the SendGrid Dashboard, the SMTP Relay, and the Web API v3. Each has different use cases, limits, and capabilities.

How to Add Attachments via the SendGrid Dashboard

The dashboard method is the simplest entry point — no code required.

Step 1 — Log in to your SendGrid account and navigate to Email API → Integration Guide, or go directly to the email editor.

Step 2 — Create a new Single Send under Marketing → Single Sends if you’re sending a campaign, or use the Dynamic Templates section for transactional emails.

Step 3 — In the email builder, look for the attachment icon (paper clip) in the toolbar when using the Design Editor. Click it to upload your file directly from your device.

Step 4 — Set the file name as it should appear to recipients. This is separate from the actual file name on your machine and controls what they see in their email client.

Step 5 — Review the file size. SendGrid’s dashboard enforces a 20MB total attachment limit per email. Exceeding this causes the send to fail silently in some cases.

Step 6 — Send a test email to yourself before launching the campaign to confirm the attachment arrives correctly and is not corrupted.

Note: The dashboard editor is best suited for one-off campaigns. For high-volume or automated attachment sending, the API approach gives you far more control.

How to Add Attachments via the SendGrid Web API v3

This is the most powerful and most commonly used method for developers, automation tools, and transactional email systems.

The Basic API Structure

SendGrid’s v3 API uses a JSON payload. Attachments are passed as a base64-encoded string inside the attachments array.

{

  “personalizations”: [

    {

      “to”: [{ “email”: “recipient@example.com” }]

    }

  ],

  “from”: { “email”: “sender@yourdomain.com” },

  “subject”: “Your File Is Attached”,

  “content”: [

    {

      “type”: “text/plain”,

      “value”: “Please find the attached file.”

    }

  ],

  “attachments”: [

    {

      “content”: “BASE64_ENCODED_FILE_CONTENT”,

      “type”: “application/pdf”,

      “filename”: “report.pdf”,

      “disposition”: “attachment”,

      “content_id”: “report”

    }

  ]

}

Breaking Down the Attachment Object

Each attachment in the array requires specific fields:

content — The file encoded as a base64 string. This is mandatory. You must encode the raw binary of your file before including it here.

type — The MIME type of the file. Common values include application/pdf, image/png, image/jpeg, application/vnd.ms-excel, application/zip. Always use the correct MIME type — mismatches cause rendering issues on recipient clients.

filename — What the recipient sees as the file name. Keep it clean and relevant. Avoid special characters.

disposition — Either attachment (the file appears as a downloadable attachment) or inline (the file is embedded in the email body, typically used for images). Default is attachment.

content_id — Required when using inline disposition to reference the file in your HTML body using <img src=”cid:content_id_value”>. Optional for standard attachments.

How to Encode Files to Base64 for SendGrid

This is where most developers trip up. SendGrid requires your file content to be base64-encoded — not the file path, not a URL, but the actual encoded binary content.

In Node.js

const fs = require(‘fs’);

const filePath = ‘./report.pdf’;

const fileContent = fs.readFileSync(filePath);

const base64Content = fileContent.toString(‘base64’);

In Python

import base64

with open(‘report.pdf’, ‘rb’) as f:

    file_data = f.read()

base64_content = base64.b64encode(file_data).decode(‘utf-8’)

In PHP

$fileContent = file_get_contents(‘report.pdf’);

$base64Content = base64_encode($fileContent);

Once you have the base64 string, drop it directly into the content field of your attachment object.

Sending Attachments With the SendGrid Python SDK

Using the official SDK simplifies the process significantly and handles encoding internally.

import base64

from sendgrid import SendGridAPIClient

from sendgrid.helpers.mail import Mail, Attachment, FileContent, FileName, FileType, Disposition

message = Mail(

    from_email=’sender@yourdomain.com’,

    to_emails=’recipient@example.com’,

    subject=’Attached: Your Report’,

    plain_text_content=’Please find the attached report.’

)

with open(‘report.pdf’, ‘rb’) as f:

    data = f.read()

encoded = base64.b64encode(data).decode()

attachment = Attachment(

    FileContent(encoded),

    FileName(‘report.pdf’),

    FileType(‘application/pdf’),

    Disposition(‘attachment’)

)

message.attachment = attachment

sg = SendGridAPIClient(‘YOUR_API_KEY’)

response = sg.send(message)

print(response.status_code)

The SDK’s Attachment class handles the object structure so you don’t need to manually construct the JSON.

Sending Attachments via SMTP Relay

If you’re using SendGrid as an SMTP relay (common with legacy applications, WordPress, or email plugins), attachments work through the standard SMTP multipart/mixed encoding.

SMTP settings for SendGrid:

• Server: smtp.sendgrid.net
• Port: 587 (TLS) or 465 (SSL)
• Username: apikey (literally the word “apikey”)
• Password: Your SendGrid API key

Most SMTP libraries (PHPMailer, Nodemailer, Python’s smtplib with email package) handle attachment encoding automatically. Here’s an example with Nodemailer:

const nodemailer = require(‘nodemailer’);

const transporter = nodemailer.createTransport({

  host: ‘smtp.sendgrid.net’,

  port: 587,

  auth: {

    user: ‘apikey’,

    pass: ‘YOUR_SENDGRID_API_KEY’

  }

});

await transporter.sendMail({

  from: ‘sender@yourdomain.com’,

  to: ‘recipient@example.com’,

  subject: ‘File Attached’,

  text: ‘See attached.’,

  attachments: [

    {

      filename: ‘report.pdf’,

      path: ‘./report.pdf’

    }

  ]

});

Nodemailer handles the base64 encoding automatically when you pass a file path.

SendGrid Attachment Limits and Restrictions

Understanding SendGrid’s limits prevents surprises in production.

File size limits:

• Maximum attachment size per email: 20MB total (across all attachments combined)
• Single file maximum: No separate per-file limit stated, but stay under the 20MB total

Number of attachments:

• No hard limit on the number of attachment objects in the API payload, but combined size must stay under 20MB

File type restrictions: SendGrid blocks certain file types that are commonly used for malware distribution. These include .exe, .bat, .cmd, .com, .scr, .vbs, and other executable formats. If you need to send these, compress them into a .zip first — though this may still trigger spam filters at the recipient’s mail server level.

Base64 overhead: Base64 encoding increases file size by approximately 33%. A 15MB PDF becomes roughly 20MB after encoding — right at the limit. Plan your file sizes accordingly.

Statistics: Research from Litmus shows that 46% of all emails are opened on mobile devices, where large attachments are especially problematic. Keeping attachments under 5MB dramatically improves the mobile experience.

How to Send Inline Images With SendGrid

Inline images are embedded directly in the email body rather than appearing as downloadable attachments. They improve visual rendering for HTML emails and avoid the “attachment” label in email clients.

{

  “attachments”: [

    {

      “content”: “BASE64_ENCODED_IMAGE”,

      “type”: “image/png”,

      “filename”: “logo.png”,

      “disposition”: “inline”,

      “content_id”: “company_logo”

    }

  ],

  “content”: [

    {

      “type”: “text/html”,

      “value”: “<html><body><img src=\”cid:company_logo\”><p>Hello!</p></body></html>”

    }

  ]

}

The cid: reference in the src attribute must exactly match the content_id value in the attachment object. Case-sensitive.

How to Add Multiple Attachments

Simply add multiple objects to the attachments array:

“attachments”: [

  {

    “content”: “BASE64_OF_PDF”,

    “type”: “application/pdf”,

    “filename”: “proposal.pdf”,

    “disposition”: “attachment”

  },

  {

    “content”: “BASE64_OF_EXCEL”,

    “type”: “application/vnd.openxmlformats-officedocument.spreadsheetml.sheet”,

    “filename”: “pricing.xlsx”,

    “disposition”: “attachment”

  }

]

Always verify that combined file sizes stay under 20MB after base64 encoding.

Common SendGrid Attachment Errors (And How to Fix Them)

Error: 400 Bad Request — Invalid base64 content

Cause: The file was encoded incorrectly or the base64 string contains whitespace or newline characters.

Fix: Strip all whitespace from the base64 string before passing it to the API:

base64_content = base64.b64encode(data).decode(‘utf-8’).replace(‘\n’, ”)

Error: Attachment arrives corrupted

Cause: The wrong MIME type was specified, or the file was encoded as UTF-8 text instead of binary.

Fix: Always open files in binary mode (‘rb’ in Python, readFileSync without encoding in Node.js) before encoding. Verify MIME type matches the actual file format.

Error: Attachment blocked by recipient’s spam filter

Cause: Large file size, suspicious file type, or lack of email authentication.

Fix: Ensure your domain has SPF, DKIM, and DMARC records configured in SendGrid. Research from Validity shows that authenticated emails are 36x less likely to be blocked by spam filters. Keep attachments small and stick to common file types.

Error: Inline image not displaying

Cause: The content_id in the attachment object doesn’t match the cid: reference in the HTML.

Fix: Double-check that the content_id value and the cid: string are identical, including capitalization.

Error: 413 Payload Too Large

Cause: Total email payload exceeds SendGrid’s limits.

Fix: Reduce file size, compress files before attaching, or use a cloud storage link instead of a direct attachment for very large files.

Best Practices for SendGrid Attachments

Use cloud links for large files. Instead of attaching a 15MB video walkthrough, host it on Google Drive, Dropbox, or your own CDN and link to it. This keeps emails lightweight and improves deliverability significantly. According to HubSpot, emails under 2MB have significantly higher deliverability rates than those approaching size limits.

Name files descriptively. Q2_Proposal_YourCompany_2025.pdf outperforms document1.pdf in every way — it looks professional, aids searchability, and reduces recipient confusion.

Always send a test first. Test across multiple email clients (Gmail, Outlook, Apple Mail) before going live. Services like Litmus or Email on Acid let you preview how attachments render across 90+ clients.

Compress files when possible. PDFs can often be compressed 30–50% without visible quality loss using tools like Smallpdf or Adobe Acrobat. ZIP archives reduce multiple files into a single, smaller package.

Avoid attaching executables. Even when legitimate, .exe and similar file types trigger spam filters at virtually every major mail provider. Use alternative delivery methods for software distribution.

Monitor your deliverability metrics. SendGrid’s Activity Feed and Email Statistics dashboard show open rates, bounce rates, and spam report rates. A spike in spam reports often correlates with attachment issues. The industry average spam complaint rate threshold is 0.1% — exceeding this can get your account suspended.

Authenticate your sending domain. SPF, DKIM, and DMARC are not optional if you care about deliverability. Google and Yahoo both require email authentication for bulk senders as of 2024. SendGrid walks you through this in the Sender Authentication section.

How Attachments Affect Email Deliverability

This is the part most guides skip, and it’s critical.

Attachments add weight — literal and figurative — to your emails. Every major inbox provider (Gmail, Outlook, Yahoo) runs content analysis on incoming emails, and attachments are a high-signal input.

Spam score factors tied to attachments:

• File type: PDFs are generally trusted; executables are not
• File size: Larger files correlate with higher spam scores
• Sender reputation: New or unverified senders sending attachments are flagged heavily
• Content consistency: Attachments that don’t relate to the email body content trigger filters
• Encryption: Password-protected ZIP files often trigger immediate spam flags because filters can’t scan the content

Research from Return Path (now Validity) found that emails with attachments from domains with poor sender reputation have a 23% lower inbox placement rate compared to those from established, authenticated senders.

Build your sender reputation gradually. Warm up new sending domains before including attachments in bulk sends.

Using Dynamic Templates With Attachments

If you use SendGrid’s Dynamic Templates for transactional emails, you can still include attachments via the API — they’re simply added to the same request payload.

{

  “personalizations”: [

    {

      “to”: [{ “email”: “user@example.com” }],

      “dynamic_template_data”: {

        “first_name”: “Jordan”,

        “order_id”: “ORD-8821”

      }

    }

  ],

  “from”: { “email”: “orders@yourstore.com” },

  “template_id”: “d-your-template-id-here”,

  “attachments”: [

    {

      “content”: “BASE64_ENCODED_RECEIPT”,

      “type”: “application/pdf”,

      “filename”: “order-receipt-ORD-8821.pdf”,

      “disposition”: “attachment”

    }

  ]

}

Dynamic templates define the email body. Attachments are independent of the template and are simply appended to the request.

Attaching Files Stored in Cloud Storage (AWS S3, Google Cloud)

If your files live in cloud storage, fetch them programmatically before encoding:

Node.js with AWS S3

const AWS = require(‘aws-sdk’);

const s3 = new AWS.S3();

const params = { Bucket: ‘your-bucket’, Key: ‘report.pdf’ };

const data = await s3.getObject(params).promise();

const base64Content = data.Body.toString(‘base64’);

Then pass base64Content into the SendGrid attachment payload as normal.

This pattern is common in serverless architectures where local file system access is limited.

Conclusion

Adding attachments in SendGrid is straightforward once you understand the underlying mechanics — base64 encoding, MIME types, the attachment object structure, and the delivery limits that govern what reaches the inbox.

The API method gives you full programmatic control and scales effortlessly. The dashboard works for one-off sends. SMTP relay bridges legacy systems. Whichever path you use, the same rules apply: keep files small, encode correctly, authenticate your domain, and test before you send.

The bigger picture: Attachments are a tactic. Getting your emails in front of the right people at the right time is the strategy. If your outbound email program isn’t generating consistent pipeline — response rates under 3–5% are the industry norm for cold email — the problem isn’t your attachment game. It’s the targeting, sequencing, and channel mix.