The size on disk is only one part of the generated message. MIME headers and base64 encoding add overhead, so a file that fits a provider's advertised limit can still make the message too large.

## What makes an attachment larger in transit?

Base64 encoding adds about one third to a binary file before line breaks and MIME headers are added. Email carries that encoded file as a MIME part, alongside the body and headers.

For example, a 12 MB binary file becomes roughly 16 MB of base64 before line breaks, headers, and body. Treat that as an estimate, not a provider limit.

## Which limit should I use?

Use the smallest limit among your sending service, the recipient's provider, and the path between them. Providers publish different limits and can change them. Link to the provider's current limit rather than hard-code one universal number.

If a file is near the limit, put it behind an authenticated download link instead. The message stays small. You can expire or revoke access separately from the email.

| Boundary              | What it limits                         | Example consequence                            |
| --------------------- | -------------------------------------- | ---------------------------------------------- |
| Attachment ceiling    | One file or attachment field           | The API rejects that item                      |
| Whole-message ceiling | Body, headers, and encoded attachments | The sender rejects the generated message       |
| Cloud-link transfer   | The linked download service            | The recipient follows a separate access policy |

[Gmail's personal help](https://support.google.com/mail/answer/6584?hl=en) describes a 25 MB total attachment limit. Workspace administrators can set different limits for work and school accounts. Treat both as provider-specific values.

## How should an API handle large files?

Check the encoded message size before sending. Reject or replace an oversized attachment with a clear download link. Tell the user which file caused the decision. Do not retry an unchanged oversized message.

Keep attachment names and content types accurate. A recipient's provider can reject a message because of the total size, a blocked file type, or a policy applied to the link.

## How does Bird handle attachments?

Set the `attachments` array on your `POST /v1/email/messages` request. Check the [attachments guide](/docs/guides/email/attachments) for Bird's current generated-message budget. An oversized HTTP send returns `413`. Keep raw attachment content well under the documented budget so the bodies and MIME wrapping fit.

## In short

- The limit covers the encoded message, body, headers, and attachments.
- Base64 adds roughly one third to a binary file's size.
- Check every provider in the delivery path.
- A download link avoids attachment-size failures for large files.

## Related resources

- [Email](/products/email) (product)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)
- [Getting started with email](/learn/email/getting-started-with-email) (video)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=email)