Sign in
Attachments

Create an attachment upload session

Create a resumable upload session for a large attachment (up to 150 MB). Returns a pre-signed URL where you upload the file bytes directly using PUT.

Upload sessions expire one hour after creation. Once you upload the file to the returned URL, call the complete endpoint to finalize the upload. After completion, reference the attachment_id in a send or draft request.

Supported providers: Microsoft (Outlook / Exchange via Graph) only. Grants for Google, IMAP, Yahoo, iCloud, and EWS are rejected with a 401 Unauthorized error.

Required Microsoft scopes (at least one): Mail.Send, Mail.ReadWrite, or Mail.ReadWrite.Shared.

For the full flow, prerequisites, and error handling, see Send large attachments.

post/v3/grants/{grant_id}/attachment-uploads

Path parameters

grant_idstring required

The ID of the grant to create the upload session for.

Request body

filenamestring required

The name of the file as it will appear in the email. No allowlist or sanitization is applied.

content_typestring required

The MIME type of the file (for example, application/pdf, image/png). No MIME allowlist is applied — any non-empty string is accepted and passed through to storage.

sizeinteger

Expected file size in bytes. Recommended — when provided, Nylas validates that the uploaded object matches this size at completion. If omitted, the size-match check is skipped and any non-zero upload is accepted. Maximum: 157286400 (150 MB).

Example request

{
  "filename": "quarterly-report.pdf",
  "content_type": "application/pdf",
  "size": 5242880
}

Response

Upload session created.

request_idstring

The request ID.

Example response

{
  "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"
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.