Most email sends cap attachments at 25 MB, which is fine until a user tries to send a video or a design file. The standard Nylas send embeds attachments in the request body, so the whole request is capped well below what a big file needs.
For larger files, Nylas has a separate upload flow. You push the file to managed storage first, then reference it by ID when you send, which lifts the ceiling to 150 MB on Microsoft accounts connected through Microsoft Graph.
How do I send attachments over 25 MB?
Section titled “How do I send attachments over 25 MB?”The standard send endpoint embeds attachments in the request, capping it at 3 MB as JSON or 25 MB as multipart form data. To go bigger, use the attachment-uploads API: POST the file to /v3/grants/{grant_id}/attachment-uploads, call complete to finalize, then reference the returned attachment ID when you send. This flow supports files up to 150 MB, in beta.
The request below starts an upload session for a large file.
curl --request POST \ --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachment-uploads' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \ --data-raw '{ "filename": "document.pdf", "content_type": "application/pdf", "size": 1048576 }'Which providers support large attachments?
Section titled “Which providers support large attachments?”The attachment-uploads API works only on Microsoft accounts connected through Microsoft Graph (Outlook and Exchange Online). Google, IMAP, Yahoo, iCloud, and on-premises EWS grants are rejected with a 401 Unauthorized, so for those 5 provider types you use the standard 25 MB multipart flow instead. There’s no unified large-attachment path across every provider, because the underlying storage is Microsoft-specific.
Exchange Online also enforces a 35 MB default maximum message size. Even when Nylas accepts a larger upload, Exchange rejects the outbound message if the file plus overhead exceeds the mailbox or transport limit, since that cap is set by Microsoft.
Things to know about large attachments
Section titled “Things to know about large attachments”Two limits sit in series, so plan for both. Nylas accepts uploads up to 150 MB, but the recipient’s mail server has the final say: the 35 MB Exchange Online default often bites first, and other recipient providers impose their own caps. Test against real mailboxes before promising users a specific size.
The feature is in beta, so the behavior is stable but the API may change before general availability. For files under the threshold, the standard attachments flow is simpler and works on every provider.
What’s next
Section titled “What’s next”- Send large attachments reference for the full 4-step upload flow and error handling
- Send email with attachments for files under 25 MB
- Using the Attachments API for the standard attachment limits
- Send email for the base send request