Skip to content
Skip to main content

Using the Attachments API

Last updated:

The Attachments APIs allow you to download or get the metadata about an existing attachment, but you use the Messages or Drafts APIs to add or modify the attachments.

What counts as an attachment?

Section titled “What counts as an attachment?”

In messages, an attachment is any file that is included either inline as part of a message, or attached as a separate file to the message.

However, major email providers such as Google and Microsoft have their own cloud storage (“drive”) services, which usually appear as links in the message body instead of attachments on the message object. Google Drive allows users to attach files either as a link, or as an actual attachment. Microsoft One Drive attachments always appear as links in the message body.

Attachment schemas and size limits

Section titled “Attachment schemas and size limits”

Choose how to attach files

How you attach a file depends on its size. Use multipart form data for most messages. JSON works for small files. Upload sessions are only for files over 25 MB on a Microsoft grant, covered in Send large attachments.
Diagram as text
  • Your app: Attach files to a message or draft: Your app adds files when it sends a message, creates a draft, or updates a draft. The same attachment options work in all three cases. Requests: POST /v3/grants/{grant_id}/messages/send, POST /v3/grants/{grant_id}/drafts, and PUT /v3/grants/{grant_id}/drafts/{draft_id}.
    • Also keep in mind: Inline images: with JSON, set content_id on the attachment and use cid:<content_id> in an <img> tag. With multipart, the file's form field name is its content ID.
    • Also keep in mind: The recipient's mail server can still reject a message under these limits. Exchange Online accepts 35 MB per message by default.
    • Also keep in mind: Agent Accounts use JSON or multipart. Upload sessions aren't available, and the account's outbound message size limit also applies.
  • Ends in one of:
    • Recommended for most messages → Send files as separate parts: Multipart form data. The message and each file travel as separate parts of one request. Works for every provider, up to 25 MB. Request: Content-Type: multipart/form-data, with the message JSON as one form field and each file as its own part.
    • Also supported, small files only → Embed small files in the message JSON: Each file is encoded as text (Base64) inside the message JSON. The whole request must stay under 3 MB. Request: Content-Type: application/json, with each file's Base64 content in the attachments array.
    • Only for Microsoft, files over 25 MB → Upload the file first, then send (beta): Upload session. Your app uploads the file in a separate step, then sends the message with a reference to it within 1 hour. For files from 25 MB to 150 MB. Request: POST /v3/grants/{grant_id}/attachment-uploads, then send with its attachment_id. Other providers get a 401 (not authorized).

Nylas supports two ways to add attachments to messages and drafts:

  • Recommended: the multipart/form schema. You break your message into parts, each with its own MIME format. It handles requests up to 25MB on every provider.
  • Also supported: the application/json schema. You pass attachment content as Base64-encoded strings in the attachments object on a Message or Draft. The whole request must stay under 3MB, so use it only for small files.

For one specific case, files over 25MB on a Microsoft grant, use upload sessions to send attachments up to 150MB.

JSON schema

Section titled “JSON schema”

When you add attachments to messages and drafts using the application/json schema, you pass the contents of the attachments as Base64-encoded strings in the attachments object, as in the following example.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "Happy Birthday from Nylas!",
    "body": "Wishing you the happiest of birthdays. <img src=\"cid:123456hbd\"> \n Fondly, \n Nylas",
    "to": [{
      "name": "Leyah Miller",
      "email": "[email protected]"
    }],
    "attachments": [
      {
        "content_type": "image/png; name=\"nylas-hbd.png\"",
        "filename": "nylas-hbd.png",
        "content": "<Base64-encoded picture content>",
        "content_id": "123456hbd"
      },
      {
        "content_type": "application/ics",
        "filename": "invite.ics",
        "content": "<Base64-encoded ICS file>",
        "content_id": "7890bdnyl"
      }
    ]
  }'

Multipart schema

Section titled “Multipart schema”

When you add attachments to messages or drafts using the multipart/form schema, you break the message into parts, each of which can have its own MIME format. The message schema at the start of a multipart request is the same as in a normal cURL request.

Nylas recommends using this schema if you’re adding a lot of attachments or if the files are large to avoid encountering provider limitations.

In most cases, you should use an SDK for your project language to prepare multipart form data, since most languages include a helper library that simplifies formatting.

Add attachments to messages or drafts

Section titled “Add attachments to messages or drafts”

You can add attachments to a message when you send it, or when you create or update a draft, by adding the attachments as content to the attachments array.

If a draft already has attachments and you send an update request with an attachments array, Nylas replaces the existing attachments list on the draft with the exact list you provide.

The encoding format you use depends on the total size of the HTTP payload of your message, as noted above.

Nylas recommends using the multipart/form-data schema if you’re adding a lot of attachments, or if the attachments are large. Nylas can send up to 25MB of attachments using multipart before encountering provider limitations.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "attachments": [
      {
        "content_type": "image/png; name=\"logo.png\"",
        "filename": "logo.png",
        "content": "<Base64-encoded picture content>"
      },
      {
        "content_type": "application/ics",
        "filename": "invite.ics",
        "content": "<Base64-encoded ICS file>"
      }
    ]
  }'

Get attachment information

Section titled “Get attachment information”

Use the Return Attachment Metadata endpoint to get information about specific attachments by ID.

To find the attachment ID, you can start with the ID of the message that the file is attached to, then make a Get Message request using field selection (?select=attachments) to return just the attachments object from the message. From there you can parse the response to find the ID of the attachment you want.

Update or remove an attachment from a draft

Section titled “Update or remove an attachment from a draft”

Nylas only updates the fields you include in your requests, so you can make an Update Draft request and only pass the attachments object to update just the attachments.

To update a file’s content or filename, update the attachments list with the corrected content. Nylas replaces the entire attachments array with your new values.

To remove a attachment from a draft, make an update draft request, include just the attachments object, and leave out the file you want to remove.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "attachments": [{
      "content_type": "image/png; name=\"logo.png\"",
      "filename": "pic.png",
      "content": "<BASE_64_PICTURE_CONTENT>"
    }]
  }'

Working with inline attachments

Section titled “Working with inline attachments”

How you work with inline attachments depends on which schema you’re using to send your message.

If you’re using the application/json schema, set up <cid> references in the message body where the files should appear, then pass the CIDs as the content_id for the associated attachment. If Nylas can’t find the associated cid reference, the attachment is still added to the message, but does not display inline. The cid should only be alphanumeric characters.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "Happy Birthday from Nylas!",
    "body": "Wishing you the happiest of birthdays. <img src=\"cid:123456hbd\"> \n Fondly, \n Nylas",
    "to": [{
      "name": "Leyah Miller",
      "email": "[email protected]"
    }],
    "attachments": [
      {
        "content_type": "image/png; name=\"nylas-hbd.png\"",
        "filename": "nylas-hbd.png",
        "content": "<BASE_64_PICTURE_CONTENT>",
        "content_id": "<CID>"
      },
      {
        "content_type": "application/ics",
        "filename": "invite.ics",
        "content": "<BASE_64_ICS_FILE>",
        "content_id": "<CID>"
      }
    ]
  }'

If you include a content_id in an attachment, Nylas assumes it should be displayed inline.

If you’re using the multipart/form-data schema, the form field name of each file is its content ID. Reference it in an <img> tag in the message body, as in <img src="cid:123456aklkdfanl">, to display the file inline.