Send and download email attachments with Nylas

Email is how most files still move between people: the signed contract, the PDF invoice, the logo embedded in a newsletter. If your app sends or processes mail, it has to handle attachments, and doing that against each provider means Gmail's attachment encoding, Microsoft Graph's, and raw MIME for IMAP. The Nylas Email API gives you one model for both directions: attach files to outbound messages with the same call you use to send, and pull files off inbound messages with a read-only Attachments API.

This post covers both halves from two angles: the HTTP API for your backend, and the nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm checking a file came through.

Two APIs: one to attach, one to read

There's a split worth understanding up front. You add attachments through the Messages or Drafts API, as part of sending or saving a message, and you read existing attachments through the dedicated Attachments API. The Attachments API is read-only: it downloads bytes and returns metadata, but it never adds files. That division keeps the model simple, since attaching is part of composing a message and reading is a separate concern.

The size of what you're attaching decides how you encode it on the way out. Small files ride inline in the JSON request, larger ones move to a multipart request, and very large files use a separate upload step. On the way in, every attachment, regardless of how it was sent, is fetched the same way: by its attachment_id together with the message_id it belongs to. Get those two ideas straight and the rest is mechanical.

Attach a small file inline with Base64

For files that keep the whole request under 3 MB, the simplest path is the application/json schema. You pass each attachment in an attachments array with its content_type, filename, and the file bytes as a Base64-encoded content string. The 3 MB ceiling covers the entire HTTP request, not just the file, so it's the right path for a small PDF or image and nothing bigger.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Your invoice",
    "body": "The invoice is attached.",
    "to": [{ "email": "[e-mail]" }],
    "attachments": [
      {
        "content_type": "application/pdf",
        "filename": "invoice.pdf",
        "content": "<Base64-encoded file content>"
      }
    ]
  }'

The CLI does the Base64 encoding for you. nylas email send --attach ./invoice.pdf reads the file, encodes it, and includes it in the send, and you can pass --attach more than once to send several files. The same --attach flag works on nylas email drafts create, so a draft can carry its attachments before it's ever sent.

Send larger files with multipart or an upload session

Once the request would exceed 3 MB, switch encodings. Above that limit you send the message as a multipart/form-data request instead of JSON, which providers cap at 25 MB for the full message. The attachment fields are the same; only the transport changes. That covers the large majority of real attachments, from multi-megabyte decks to short video clips.

For files beyond 25 MB, there's a separate pre-upload flow that's currently Microsoft-only and handles attachments up to 150 MB. You create an upload session, PUT the file bytes to the returned URL, then reference the resulting attachment by ID in your send. The send large attachments guide walks through that flow. One Microsoft-specific gotcha it covers: Exchange Online defaults to a 35 MB send size, so you raise the mailbox limit toward 150 MB before sending large files, because Nylas accepting the upload doesn't guarantee Exchange will deliver it. The practical ladder is simple: under 3 MB inline, under 25 MB multipart, and the upload session only when you genuinely need very large files on a Microsoft account.

Embed an inline image with a content ID

Not every attachment is a separate download; a logo or a chart in the body of an HTML email is an inline attachment. You mark one by giving the attachment a content_id and referencing that ID from the HTML body with a cid: URL, so <img src="cid:logo123"> renders the attachment whose content_id is logo123 right where you place the tag.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Welcome aboard",
    "body": "<p>Welcome!</p><img src=\"cid:logo123\">",
    "to": [{ "email": "[e-mail]" }],
    "attachments": [
      {
        "content_type": "image/png",
        "filename": "logo.png",
        "content": "<Base64-encoded image>",
        "content_id": "logo123"
      }
    ]
  }'

The difference between an inline image and a regular attachment is the content_id and the cid: reference, which together set the attachment's disposition to inline so the mail client renders it in place rather than listing it as a download. Drop the content_id and the same file becomes a standard attachment the recipient downloads separately. That one field is the whole distinction.

The inline mechanism works on drafts too, through the same attachments array, so a templated welcome email can carry its logo from draft to send. And because an inline image is part of the message rather than a remote URL, it renders even in clients that block remote images for privacy, which is a reason to embed a logo with cid: rather than hotlink it from a server.

Set the right content type

Every attachment needs a content_type, the MIME type that tells the recipient's mail client what the file is and how to handle it. A PDF is application/pdf, a PNG is image/png, and a calendar invite is application/ics. Get it wrong and a client may refuse to preview the file, or fail to render an inline image, even when the bytes are perfectly correct.

Match the content_type to the actual file rather than guessing from the extension, especially for inline images where the wrong type can stop the cid: reference from displaying. Nylas documents the supported media types for attachments, which is the place to check when a particular file type isn't behaving the way you expect on send or download.

List the attachments on a message

When mail arrives, the message object tells you which attachments it carries, and the Attachments API reads them. To see what's on a message from the terminal, nylas email attachments list <message-id> prints each attachment with its filename, type, and size. It's the fastest way to inspect what came in before you decide what to pull down.

nylas email attachments list <message-id>

Each entry has an id, which is the attachment_id you'll use to fetch the file, along with its filename, content_type, and size. An inbound newsletter might list a logo marked inline alongside a PDF marked as a regular attachment, and the metadata tells you which is which before you spend bandwidth downloading anything.

You often don't even need a separate call for this. The message object itself carries an attachments array, where each entry holds the id, filename, size, content_type, and an is_inline flag. So when you fetch or receive a message, you already have the metadata to decide what to download, and is_inline tells you whether an attachment is an embedded image or a file the recipient would download on its own.

Get an attachment's metadata

When you have an attachment_id and want its details without the bytes, GET /v3/grants/{grant_id}/attachments/{attachment_id} returns the metadata. There's a requirement that trips people up: you must pass the message_id as a query parameter, because an attachment is identified relative to the message it belongs to, not on its own.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The CLI command mirrors that requirement: nylas email attachments show <attachment-id> <message-id> takes both IDs as positional arguments, because the metadata lookup needs the message context just like the API does. Reading metadata first is useful when you want to check a file's size or type before committing to the download, for example to skip anything over a threshold or filter by content type.

Download the file

To get the bytes, GET /v3/grants/{grant_id}/attachments/{attachment_id}/download streams the file. Like the metadata call, it requires the message_id query parameter, so both attachment endpoints always take the attachment ID and the message ID together. The response is the raw file, which you redirect to disk or pipe onward.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --output invoice.pdf

From the CLI, nylas email attachments download <attachment-id> <message-id> saves the file, defaulting to its original filename, and -o ./path/file.pdf writes it wherever you want. This is the call an inbound-processing agent makes after it decides a message's attachment is worth keeping: list the attachments, check the metadata, then download the ones that matter.

Process inbound attachments automatically

The read side comes together in a webhook loop. When a message arrives, the message.created webhook fires with the message object, and that object already lists its attachments with their IDs, sizes, and types. Your handler reads that array, decides which files matter, and downloads only those by pairing each attachment_id with the message's id.

That ordering keeps an inbound pipeline efficient. An invoice-processing agent, for example, can ignore inline signature images by checking is_inline, skip anything over a size threshold by reading size, and download only the PDFs it needs to parse. Because the metadata rides on the message you already received, you spend bandwidth only on the files you keep, not on everything that lands in the mailbox. The download itself is the one call that pulls bytes, so gating it on the metadata you already have is what keeps the pipeline cheap at volume.

Things to keep in mind

A few details separate a smooth attachments integration from one that returns confusing errors.

• Always pass message_id to read an attachment. Both the metadata and download endpoints require it; an attachment ID alone isn't enough to locate the file.
• Pick the encoding by size. Under 3 MB inline as Base64, under 25 MB with multipart/form-data, and the Microsoft-only upload session for files up to 150 MB.
• Inline versus attached is one field. A content_id plus a cid: reference in the HTML body makes an image render in place; without it, the file is a separate download.
• Add through Messages or Drafts, read through Attachments. The Attachments API never adds files; you attach when you send or draft.
• Check metadata before downloading. Reading size and content_type first lets you skip oversized or unwanted files without spending the bandwidth.
• is_inline separates embedded images from files. On inbound mail, read it to skip inline logos and signatures and download only the real attachments.
• Raise the Exchange mailbox limit for large files. Exchange Online defaults to a 35 MB send size, so the 150 MB upload session needs that raised first; Nylas accepting the file doesn't guarantee Exchange delivers it.

Wrapping up

Attachments come down to two flows. Outbound, you add files to a send or a draft, choosing the encoding by size: Base64 inline under 3 MB, multipart under 25 MB, an upload session for very large Microsoft files. Inbound, you list a message's attachments, read their metadata, and download the bytes, always pairing the attachment_id with its message_id. The same handful of calls, or the nylas email attachments commands, cover every provider Nylas connects, so a logo embedded in a Gmail newsletter and a PDF on an Exchange message are the same code path.

Where to go next:

• Attachments overview — encoding schemas, inline images, and limits
• Send attachments and download attachments — task-focused walkthroughs
• Send large attachments — the Microsoft-only upload-session flow up to 150 MB
• Get an attachment and download an attachment — the endpoint references