Best Email Attachments API for Developers

The best email attachments API is the one that lets your application upload a file once, receive a short-lived reference, and attach that reference to a retriable send request. Inline base64 still has a place for small content already in memory, while a controlled download link is better when the recipient needs revocation, expiry, or an access log.

There is no safe universal file-size rule. Provider upload limits, final MIME message limits, recipient gateways, and security policy all matter. Check those boundaries before choosing an attachment path.

Email attachment API patterns at a glance

The right pattern depends on the complete path from application memory to the recipient's mail client. A provider can accept an upload and still reject the final message after MIME encoding, or the recipient's gateway can block a file type that the sender accepts.

How are files represented in an email API?

Email attachments are MIME parts. Each part carries headers such as a filename, content type, disposition, and sometimes a content ID for an image displayed inside HTML. Binary content must survive text-oriented email transport, so APIs that accept inline files commonly require base64.

Base64 turns each three bytes of input into four encoded characters. That expansion is one reason an inline JSON request can hit a request-body limit before the original file appears especially large. MIME headers, boundaries, the message body, and transfer encoding also contribute to the final message size.

An API generally exposes one or more of these forms:

1. Inline content with fields such as filename, content, and type.

2. A binary upload endpoint that returns an attachment identifier.

3. A delegated upload URL that lets a browser or hosted agent upload without receiving the main API key.

4. A hosted link placed in the message body rather than a MIME attachment.

Multipart upload avoids putting base64 in the upload request, but it does not remove encoding from the final email. The final MIME message still has to fit the sender's and recipient's limits.

When should you attach a file or send a link?

Attach a modest file when the recipient needs a durable copy in the message, offline access matters, and the file type is expected. Receipts, calendar files, and ordinary PDFs often fit this case.

Use a controlled link when access must expire, be revoked, or be logged. Links also suit files that exceed an attachment or final-message limit. The trade-off is that the recipient depends on the link and storage service remaining available.

Security policy can override convenience. Once an attachment is delivered, the sender cannot revoke every copy. A short-lived link can reduce that exposure, but only if the download endpoint authenticates the intended recipient or uses a sufficiently protected capability URL. Avoid putting secrets in query strings or logs, and never assume a signed URL is harmless because it expires.

Do not decide from file size alone. Confirm:

• the API's per-file and attachment-count limits;

• the maximum request size for inline content;

• the final encoded message limit;

• allowed and blocked file types;

• recipient gateway policy;

• required expiry, revocation, and audit controls.

How does upload-then-reference work?

The upload-reference pattern separates file transfer from message submission:

1. Validate the local file name, type, and size.

2. Upload the file's exact bytes yourself, or let the client upload them through a delegated URL.

3. Receive an attachment identifier.

4. Submit the email with that identifier and an idempotency key.

5. Record the message and attachment identifiers for support and audit work.

6. Test the received file, not only the provider's accepted response.

This pattern keeps normal file bytes out of JSON and allows a hosted client to upload without holding the sending credential. It also makes retries easier to reason about: the file upload has its own result, while the message submission can be retried with an idempotency key.

The attachment reference is usually temporary. Create it close to the send, do not store it as a permanent asset identifier, and handle an expired or missing reference as a new upload rather than guessing that the old reference remains valid.

What attachment limits does Sendmux use?

For the Sendmux Sending API, uploaded references are the preferred path for normal files. A direct or delegated binary upload accepts up to 18 MiB, each email can contain up to 10 attachments, and the final sent message must fit within 25 MB. Base64 still counts towards request size, and the final encoded email remains subject to the message limit.

Mailbox send workflows have a separate boundary: each uploaded mailbox attachment is limited to 7,500,000 bytes, and inline base64 content is limited to 5,000,000 bytes. Both mailbox upload forms return a blob ID for the send request.

Sendmux checks common file formats and rejects executables and archives. A file that is too large, unsupported, or inconsistent with its claimed type fails with a validation or payload-size error. Fix that input before retrying.

Local MCP clients can upload from an approved file path and receive an attachment_id. Hosted clients can create a delegated upload, send the bytes to its short-lived URL, and then pass the returned reference to the send tool. This keeps large base64 strings and file bytes out of the model prompt.

Inbound mailbox messages expose attachment metadata and a short-lived download URL. If the URL expires, re-read the message or attachment metadata to obtain a fresh one. Do not construct a download URL manually.

How do Microsoft Graph and Gmail handle larger files?

Microsoft Graph accepts a file attachment directly for files under 3 MB. For files from 3 MB to 150 MB, its documented Outlook flow creates an upload session and uploads byte ranges before the message is sent. That is another form of upload-then-reference, even though the final object is attached to a draft message.

The Gmail API supports simple media upload, multipart upload with metadata, and resumable upload. Its documentation recommends resumable upload for large files or connections where interruption is likely. Gmail API usage is also governed by per-user quota units, so sending architecture must account for both payload handling and request quotas.

Raw SMTP does not remove these constraints. The client still constructs a MIME message, and the accepting server can reject the message because of size, content, authentication, or policy.

Why do attachment sends fail?

Attachment failures fall into four useful groups:

• Preparation: invalid base64, a false content type, an unsafe filename, or an unreadable source file.

• Submission: an expired attachment reference, incorrect content length, an oversized request, or a duplicate send without idempotency protection.

• Transport: the final MIME message exceeds a provider boundary, or an SMTP server rejects the message.

• Recipient policy: a gateway blocks the file type, quarantines the message, or strips the attachment.

Keep those stages separate in logs. An upload success does not prove the message was accepted, and provider acceptance does not prove that the recipient received an intact file.

For retriable submission, use a stable idempotency key for the logical send. If a request times out, retry with the same key and body. Do not generate a new key for every network attempt, because that turns a transport retry into a second message.

How should sensitive attachments be secured?

Start with data minimisation. Do not email a sensitive file merely because the API can carry it. If an attachment is required, limit who can upload, send, and download it, scan the file at the appropriate trust boundary, and avoid logging raw bytes or capability URLs.

A link can support expiry and revocation, but it is not automatically safer. Protect the storage object, set the shortest practical lifetime, and decide whether possession of the URL is enough or whether the recipient must authenticate. Record access when the audit requirement calls for it.

For agents, keep binary files outside the prompt. Give the tool a local approved path or delegated upload URL, then return an opaque attachment reference. On inbound mail, expose metadata first and fetch or extract content only when the workflow needs it.

How do you test an attachment API?

A production test should cover more than one successful PDF:

1. Send a zero-byte or minimum-size allowed file and confirm the expected result.

2. Test just below and just above each documented size boundary.

3. Try an allowed extension with mismatched content and a blocked file type.

4. Retry the same send with the same idempotency key and confirm there is one logical message.

5. Let an upload reference or download URL expire and verify the recovery path.

6. Receive the message through a real destination gateway and compare the downloaded file hash with the original.

7. Confirm that logs and model inputs do not contain raw file bytes or reusable download credentials.

The roundtrip hash check is the strongest end-to-end signal. It catches truncated uploads, encoding mistakes, gateway transformations, and download problems that a provider's accepted response cannot reveal.

Which email attachments API should developers choose?

Choose an API that publishes separate upload, request, and final-message limits; offers upload references; supports idempotent sends; returns useful validation errors; and exposes attachment metadata on the inbound side when replies matter.

For Sendmux, the normal route is binary upload followed by attachment_id. Inline base64 is a compatibility path for small in-memory content. Mailbox workflows use blob_id, while inbound attachments use metadata and short-lived download URLs. Those boundaries make attachment behaviour explicit for both application code and agent tools.

Before adopting any provider, run the seven-case test plan against the file types and recipient gateways your application will use. The best email attachments API is the one whose documented limits, retry semantics, and security boundary survive that real path.

Sources

• Sendmux attachment documentation

• Sendmux SMTP documentation

• Microsoft Graph large attachment documentation

• Gmail API upload documentation

• Gmail API quota documentation

• RFC 4648 base encoding