Skip to content
Skip to main content

Using email headers and MIME data

The Nylas Email API allows you to work with message headers and MIME data.

The message ID header

Section titled “The message ID header”

When you send a message using the Nylas Messages API, Nylas creates a unique message_id_header value for the SMTP transaction, similar to:

4ottpfaje0kqx8iagoih0h3tp-0@mailer.nylas.com

This header is required by the provider’s SMTP server and is part of the standard email protocol. It’s visible only in the sender’s database and isn’t an object you can use or update through the API.

The provider’s SMTP server may change this value during the sending process. Avoid using message_id_header values with the @mailer.nylas.com domain for email configuration, as the provider may overwrite them.

What are email headers?

Section titled “What are email headers?”

Email headers are a collection of key-value pairs that define important information about a message (the subject, its recipients, the time it was sent, and so on). Typically, they’re included at the beginning of a message’s raw data.

A message might include multiple headers with the same name (for example, multiple Received headers), or custom headers defined by the sender. Custom headers are generally prefixed with X- (for example, X-Received).

Delivered-To: nyla@example.com
Received: Thu, 21 Mar 2024 09:27:34 -0700 (PDT)
X-Received: Thu, 21 Mar 2024 09:27:33 -0700 (PDT)
Return-Path: <EMAIL_ADDRESS>
Received: Thu, 21 Mar 2024 09:27:33 -0700 (PDT)
Date: Thu, 21 Mar 2024 11:27:33 -0500 (CDT)
From: Team Nylas <tips@nylas.com>
Reply-To: tips@nylas.com
To: nyla@example.com
Message-ID: <MESSAGE_ID>
Subject: Upgrade to Nylas API v3, now generally available
...

Using email headers

Section titled “Using email headers”

Nylas can return message headers on Get Message, Get all Messages, and Send Message requests. Set the fields query parameter to control which headers Nylas returns:

  • fields=include_headers returns the full header set on the message.
  • fields=include_basic_headers returns only the three RFC threading headers — Message-ID, In-Reply-To, and References. Use this option when you only need to track message identity and thread relationships. The response payload is significantly smaller than include_headers.

Without either parameter, Nylas doesn’t return the headers array.

Provider support

Section titled “Provider support”

fields=include_basic_headers is supported on all providers: Google, Microsoft, EAS, EWS, and IMAP.

fields=include_headers returns the full header set on Google, Microsoft, and EAS. On EWS and IMAP, it returns only the headers Nylas generates for MIME — provider limitations mean the full header set isn’t reachable. If you need Message-ID, In-Reply-To, or References on those providers, use include_basic_headers.

Get headers on Get Message and Get all Messages

Section titled “Get headers on Get Message and Get all Messages”

When you set the fields query parameter on a Get all Messages request, Nylas returns the matching headers array on each message in the list. You can also fetch a single message’s headers directly with a Get Message request.

To get only the threading headers, use fields=include_basic_headers instead. The response is identical except the headers array contains only Message-ID, In-Reply-To, and References:

Get headers on Send Message

Section titled “Get headers on Send Message”

When you set the fields query parameter on a Send Message request, Nylas includes the message’s headers array on the send response. This is useful when you need the Message-ID of a sent message — for example, to store it for later thread reconstruction, or to deduplicate inbound webhooks against messages your application sent.

Working with header data

Section titled “Working with header data”

Nylas parses both the header name and content directly from the message, so any encoded headers are also encoded in the API response. If you expect to use any encoded header data, your project must be able to decode it.

Messages might contain multiple headers with the same name. Nylas doesn’t merge or de-duplicate the list of headers. If you want to work with a specific header, Nylas recommends iterating through the headers array and selecting the one you want to use.

What is MIME data?

Section titled “What is MIME data?”

Email providers use the MIME format to represent the raw data of a message as blocks of information. MIME data is generally preceded by the MIME-Version header and the boundary that distinguishes content blocks in the message. Each block has its own Content-Type and Content-Transfer-Encoding that you can use to decode its data.

...
MIME-Version: 1.0
Content-Type: multipart/alternative;
  boundary="----=_Part_6675479_1563466077.1711038453276"


------=_Part_6675479_1563466077.1711038453276
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable


<Plaintext body content>


------=_Part_6675479_1563466077.1711038453276
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable


<HTML body content>


------=_Part_6675479_1563466077.1711038453276

You can use MIME data to get the complete information about a specific message, including the multiple formats it might accommodate. For example, the sample above offers both a plaintext and HTML version of the body content.

Get MIME data from messages

Section titled “Get MIME data from messages”

When you set the fields query parameter to raw_mime on a Get Message request, Nylas returns the grant_id, object, id, and raw_mime fields only.

The raw_mime field contains all of the Base64url-encoded MIME data from the message, starting from the MIME-Version header. You can use the boundary value to separate blocks of content within the message.

Send messages with MIME data

Section titled “Send messages with MIME data”

You can include MIME data in a Send Message request by: - Setting the mime form field in a multipart/form-data request. - Including the query parameter type=mime

curl --location 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send?type=mime' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--form 'mime="MIME-Version: 1.0
Subject: Test Raw MIME
From:  sender <sender@mail.example.com>
To: receiver <receiver@mail.example.com>
Content-Type: multipart/alternative; boundary=\"000000000000fda5260624af9e86\"


--000000000000fda5260624af9e86
Content-Type: text/plain; charset=\"UTF-8\"


Helloworld


--000000000000fda5260624af9e86
Content-Type: text/html; charset=\"UTF-8\"


<div dir=\"ltr\">Helloworld</div>


--000000000000fda5260624af9e86--"'
Section titled “Related resources”