Skip to content
Docs
or

Working with email attachments

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?

In email 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

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

  • Using the application/json schema. With this format, you pass attachment content as Base64-encoded strings in the attachments object on a Message or Draft.
  • Using the multipart/form schema. With this format, you break your email message into parts, each of which can have their own MIME format.

JSON schema

When you add attachments to email 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, application/gzip' \
  --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

When you add attachments to email messages or drafts using the multipart/form schema, you break the email 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 email messages or drafts

You can add attachments to an email 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, application/gzip' \
  --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

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

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, application/gzip' \
  --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

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, application/gzip' \
  --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, attach the files using the multipart schema, then make a Get Message request and check the form IDs to find the content IDs you can include in the message body.