Working with email attachments
✨ The Attachments API replaces the Files API in Nylas v3. For more information about changes between v2.7 and v3, see Introducing Nylas v3.
In Nylas v3, you use the Messages and Drafts APIs to add and modify files attached to email messages.
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.
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 theattachments
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.
📝 This method is limited to request payloads of 3MB or smaller. The size limit includes the entire HTTP request, not just the attachment content.
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": "Jacob Doe",
"email": "jacob.doe@example.com"
}],
"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.
📝 Multipart email messages are limited to 25MB. This size limit includes the body content.
curl --request POST \
--url https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'content-type: multipart/form-data' \
--form 'message={
"subject": "Happy Birthday from Nylas!",
"body": "Wishing you the happiest of birthdays. \n Fondly, \n -Nylas <123456aklkdfanl>",
"to": [
{
"name": "Jacob Doe",
"email": "jacob.doe@example.com"
}
]
}' \
--form 'kldj234567hbd2u=@/file/path/to/attachment/invite.ics' \
--form '123456aklkdfanl=@/file/path/to/attachment/nylas-hbd.png'
// Example Multipart Email:
From: nyla@example.com
To: jacob.doe@example.com
Subject: Happy Birthday from Nylas!
Content-Type: multipart/alternative; boundary="boundary-string"
--your-boundary
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
Wishing you the happiest of birthdays. \n Fondly, \n -Nylas
//This section is the fallback in case the email client does not support HTML.
--boundary-string
Content-Type: text/html; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
<h1>Happy Birthday!</h1>
<p>Wishing you the happiest of birthdays. <\br> Fondly, <\br> -Nylas</p>
<p>This section displays in most modern email clients.</p>
<img src="cid:the-cid-of-this-file-is-12345" alt="Happy Birthday from Nylas!"=>
--boundary-string--
--the-cid-of-this-file-is-12345
Content-Type: image/png
Content-ID: <nylas-hbd.png>
Content-Disposition: inline; filename="nylas-hbd.png"
[IMAGE content]
--the-cid-of-this-file-is-12345--
--this-is-an-invite-file
Content-Type: application/ics
Content-ID: <invite.ics>
Content-Disposition: attachment; filename="invite.ics"
[ICS file content]
--=_8ab337ec2e38e1a8b82a01a5712a8bdb--
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' \
--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.
curl --request GET \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>?message_id=<MESSAGE_ID> \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
{
"request_id": "5fa64c92-e840-4357-86b9-2aa123456789",
"data": {
"content_type": "image/png; name=\"pic.png\"",
"filename": "pic.png",
"grant_id": "<NYLAS_GRANT_ID>",
"id": "185e56cb50e12e82",
"is_inline": true,
"size": 13068,
"content_id": "<ce9b9547-9eeb-43b2-ac4e-58768bdf04e4>"
}
}
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.
curl -L 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>?select=attachments' \
-H 'Authorization: Bearer <NYLAS_API_KEY>'
{
"request_id": "041d52e4-fe02-49d9-aeb6-3f0987654321",
"data": {
"attachments": [
{
"content_disposition": "attachment; filename=\"nylas-logo.png\"",
"content_id": "ii_123456789",
"content_type": "image/png; name=\"nylas-logo.png\"",
"filename": "nylas-logo.png",
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<ATTACHMENT)ID>",
"is_inline": true,
"size": 4452
},
{
"content_disposition": "attachment; filename=\"invite.ics\"",
"content_id": "ii_987654321",
"content_type": "application/ics; name=\"invite.ics\"",
"filename": "invite.ics",
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<ATTACHMENT)ID>",
"is_inline": false,
"size": 2456
}
]
}
}
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 encoded 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' \
--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": "Jacob Doe",
"email": "jacob.doe@example.com"
}],
"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"
}
]
}'
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.