Nylas Attachments API

You can use the `attachments` schema in a [Send Message request](/docs/reference/api/messages/send-message/) to send attachments, regardless of the email provider. You use the [Drafts](/docs/reference/api/drafts/) endpoints to add and modify files attached to drafts. The Attachments endpoints let you download or get the metadata for existing attachments. For more information, see [Working with email attachments](/docs/v3/email/attachments/). If you're using draft support, the draft (including the attachment) is stored on the provider. If you're not using draft support, Nylas stores the attachment. You can make a [Get Attachment Metadata request](/docs/reference/api/attachments/get-attachments-id/) to retrieve a single attachment's metadata using its ID. ## What counts as an attachment? In Nylas, an attachment is any file included either inline as part of a message, or attached to a message as a file. Some major email providers, such as Google and Microsoft, have their own cloud storage ("drive") services. These files usually appear as links in the message body instead of attachments on the Message object. Google Drive lets users attach files either as a link, or a file. Microsoft One Drive attachments always appear as links in the message body. ## Attachment size discrepancies When Nylas returns information about an attachment, its listed size might be different from the actual size of the file. This is because of provider encryption methods, message headers, and rounding on the provider side. For example, if you receive a 3480-byte attachment in an email, Nylas might list it as 3680 bytes. ## Attachments scopes The table below lists the Attachments endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes. The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope. | Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` | | :----------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- | | **GET** `/attachments/`**GET** `/attachments//download` | `/gmail.readonly` ☑️`/gmail.modify` | `Mail.Read` ☑️`Mail.ReadWrite``Mail.ReadWrite.Shared``Mail.Read.Shared` | For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/). ## Query IMAP server directly Set the `query_imap` query parameter to `true` in your [Get Attachment Metadata](/docs/reference/api/attachments/get-attachments-id/) or [Download Attachment](/docs/reference/api/attachments/get-attachments-id-download/) requests to query the IMAP server directly instead of the Nylas database. This lets you get the most up-to-date information from the IMAP server, or data older than the default three-month retention time. Keep in mind that most IMAP servers are slow and have low [rate limits](/docs/dev-guide/platform/rate-limits/). Nylas might take more time to return responses compared to requests that don't use the `query_imap` query parameter. If an account has many folders, or you're querying for a large attachment, your request can take even longer. ## Microsoft attachment size discrepancies If you're working with Microsoft grants, you might notice a small difference between the attachment size in Nylas' response and the actual size of the downloaded file. This is because Nylas' attachment size calculation includes any MIME encoding headers. Nylas returns this value to be consistent with the provider, and so that it doesn't have to pre-process all attachment content. When working with attachments on Microsoft grants, we recommend you... - Treat the metadata `size` field as an estimate for UI display purposes. - Always use the actual downloaded file for storage calculations and file operations. - Implement flexible buffer handling when the exact byte count of a file matters to your project. - Test your Nylas integration with a number of different attachment types and sizes.