Send large attachments

The standard Send Message endpoint accepts attachments as base64-encoded content inside the JSON body, which caps the entire request at 3 MB (or 25 MB using multipart form data). For files larger than that, use the attachment-uploads API to upload the file directly to Nylas-managed storage, then reference it by ID when you send the message. This flow supports attachments up to 150 MB.

Beta feature. The attachment-uploads API is currently in beta. The behavior described here is stable, but the API may evolve before general availability.

Supported providers: Microsoft (Outlook and Exchange Online via Microsoft Graph).

Google, IMAP, Yahoo, iCloud, and EWS grants are rejected with 401 Unauthorized. For these providers, use the standard attachment flow with its 25 MB multipart limit.

Before you begin

You need the following before sending large attachments:

• A Microsoft grant with at least one of these scopes: Mail.Send, Mail.ReadWrite, or Mail.ReadWrite.Shared. See Create an Azure app for how to configure the auth app.
• An Exchange Online tenant with message size limits raised to accommodate your largest attachment (see below).

Raise the Exchange Online message size limit

Exchange Online defaults to a 35 MB maximum message size. If your attachment plus message overhead exceeds this, the send fails and recipients on Exchange-based mailboxes do not receive the message.

These limits are enforced by Microsoft, not Nylas. Even when the Nylas API accepts the upload, Exchange rejects the outbound message if the mailbox or transport limit is below the total send size.

Raise the limit using Exchange Online PowerShell as an Exchange administrator. Set the value to match your expected maximum attachment size. Changes can take up to 60 minutes to propagate.

Per-mailbox (recommended for a targeted rollout):

Set-Mailbox -Identity "[email protected]" -MaxSendSize 150MB -MaxReceiveSize 150MB

Organization-wide:

Set-TransportConfig -MaxSendSize 150MB -MaxReceiveSize 150MB

How it works

Instead of embedding the file in the send request, you:

1. Create an upload session. Nylas returns a direct-upload URL.
2. Upload the file bytes. PUT the file directly to the returned URL. No Nylas auth header required.
3. Complete the session. Nylas verifies the upload and marks the attachment as ready.
4. Send the email. Reference the attachment_id in the attachments array of your send request.

Session lifetime is 1 hour. You must complete steps 2 through 4 within this window. Once the session expires, the uploaded file is deleted from storage. Plan your workflow so the send happens inside the 1-hour window.

Step 1: Create an upload session

Make a Create Upload Session request to start the flow.

RequestResponse

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
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "attachment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "method": "PUT",
    "url": "https://storage.googleapis.com/upload/storage/v1/b/BUCKET/o?uploadType=resumable&upload_id=...",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-04-22T19:00:00Z",
    "max_size": 157286400,
    "size": 5242880,
    "content_type": "application/pdf",
    "filename": "quarterly-report.pdf",
    "grant_id": "abc123"
  }
}

Field	Required	Notes
filename	Yes	Name of the file as it appears in the email.
content_type	Yes	MIME type (for example, application/pdf, image/png). Any non-empty string is accepted.
size	No	Expected file size in bytes. Recommended. When provided, Nylas verifies the uploaded bytes match this value during completion. Maximum: 157286400 (150 MB).

Save the attachment_id from the response. You need it for steps 3 and 4.

Always set size. If you omit it, Nylas skips the size-match check at completion and accepts any non-zero upload. Providing size catches truncated or corrupt uploads before the email is sent.

Step 2: Upload the file

PUT the file bytes to the url returned in step 1. This is a Google Cloud Storage resumable upload URL, so no Nylas authorization header is required on this request.

Set Content-Type to match the value you declared in step 1. A successful upload returns HTTP 200 or 201.

curl -X PUT "{url from step 1}" \
  -H "Content-Type: application/pdf" \
  -H "Content-Length: 5242880" \
  --data-binary @quarterly-report.pdf

Use resumable uploads for large files. The url follows Google’s resumable upload protocol. For files over ~10 MB, upload in chunks using Content-Range headers so you can resume from the last successful byte if the connection drops. The GCS session URI has its own multi-day expiration that is independent of the Nylas 1-hour window.

Step 3: Complete the upload session

Once the file is uploaded, notify Nylas so it can verify the upload and mark the attachment ready to send. See the Complete Upload Session reference.

RequestResponse

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachment-uploads/<ATTACHMENT_ID>/complete' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "attachment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "grant_id": "abc123",
    "status": "ready"
  }
}

The request body is empty. Once status is ready, the attachment can be referenced in a send request.

Step 4: Send the email

Pass the attachment_id as id inside the attachments array of your Send Message or Create Draft request. Do not include content or content_type. Nylas fetches the file from storage and attaches it at send time.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": [{ "name": "Jane Smith", "email": "[email protected]" }],
    "subject": "Q1 Report",
    "body": "Please find the report attached.",
    "attachments": [
      { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
    ]
  }'

If the referenced attachment is not ready at send time (for example, it is still uploading, has failed, or has expired), the send fails. Nylas deletes the draft in both the synchronous and use_draft=true scheduled paths, and the synchronous send returns a 500 to the caller. Verify status with the Get Upload Session endpoint before you send if you aren’t sure the upload completed.

Inline attachments

To embed a large image or file inline in the email body, set content_id on the attachment entry and reference it in the HTML body using a cid: URI.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": [{ "name": "Jane Smith", "email": "[email protected]" }],
    "subject": "Q1 Report",
    "body": "<p>See chart below:</p><img src=\"cid:chart1\">",
    "attachments": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "content_id": "chart1"
      }
    ]
  }'

Nylas treats the attachment as inline when the content_id value appears as cid:{content_id} inside the message body. If you include a content_id but the body does not reference it, the file is still attached but is displayed as a regular attachment rather than inline. See Working with inline attachments for the full rules.

Upload session status

Use the Get Upload Session endpoint to check the status of an upload at any time.

Status	Meaning
uploading	Session created; Nylas is waiting for the file upload.
ready	Upload verified and complete. The attachment can be referenced in a send or draft.
failed	Upload initiation failed (for example, Nylas could not create the storage URL during session creation). Create a new session.
expired	Session was not completed within 1 hour. Create a new session.

Response shape quirk on the GET endpoint. The GET /attachment-uploads/{attachment_id} endpoint returns the raw storage record, so field names are PascalCase (for example, ID, GrantID, ExpectedSize, Status) and the response is not wrapped in the usual { request_id, data: { ... } } envelope. The response may also include additional internal fields not documented above. Rely only on the documented fields. The create and complete endpoints do use the standard envelope with snake_case keys.

Errors

All error responses follow the standard Nylas error shape:

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "error": {
    "type": "invalid_request",
    "message": "file_size exceeds maximum allowed size of 157286400 bytes"
  }
}

HTTP status	When it occurs
400 Bad Request	filename or content_type is missing, size is negative or zero, size exceeds 150 MB, or the request body is not valid JSON.
401 Unauthorized	Grant cannot be resolved, the provider is not Microsoft, the grant lacks the required Microsoft scopes, or the grant_id in the path does not match the session on the GET or complete endpoints.
404 Not Found	The attachment_id does not exist.
409 Conflict	/complete was called on a session that is already ready or has failed.
410 Gone	/complete was called on an expired session, or the session was already past expires_at.
422 Unprocessable Entity	The file is not in storage, the uploaded size does not match the declared size, or no size was declared and the object is empty.
500 Internal Server Error	Storage or database failure. Retry the operation.

Rate limiting is not enforced at the attachment-uploads service itself. Any 429 Too Many Requests response is returned by the upstream API gateway. See Sending errors for general troubleshooting.

Limits and retention

Parameter	Limit
Maximum file size	150 MB (157286400 bytes)
Session expiry	1 hour from creation
Supported providers	Microsoft (Graph)
Exchange Online default message size	35 MB. Raise via PowerShell (see Before you begin).
File retention after ready	Until expires_at (1 hour after creation). Send before the window closes.
Metadata retention	60 days. You can call GET /attachment-uploads/{attachment_id} for observability after the file is gone.

Reusing an attachment_id across sends is allowed but limited. As long as the session is ready and the file is still in storage, you can reference the same attachment_id in multiple sends. Because the file is deleted when expires_at passes, you have at most 1 hour from session creation to send. For later sends, upload the file again.

Related

• Using the Attachments API. Standard attachment flow (up to 3 MB JSON or 25 MB multipart), inline attachments, and downloading attachments.
• Sending messages with Nylas. End-to-end guide to sending and scheduling messages.
• Sending errors. Troubleshooting delivery failures.
• Create an Azure app. Set up the Microsoft auth app and scopes needed to authenticate a grant.
• API reference: Create an upload session, Get upload session, Complete upload session.