Using email headers and MIME data in Nylas

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

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).

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

When you set the fields query parameter to include_headers on a Get all Messages request, Nylas returns a list of messages that contain headers. You can use this list to find the message you want to work with, get its ID, and make a Get Message request with fields set to include_headers. Nylas returns a headers array that contains a set of key-value pairs representing the name and contents of each header, as in the following example.

Request
Response (JSON)

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/?fields=include_headers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": {
    "grant_id": "<NYLAS_GRANT_ID>",
    "object": "message",
    "id": "<MESSAGE_ID>",
    "date": 1635355739,
    "to": [{
      "name": "Nyla",
      "email": "nyla@example.com"
    }],
    "from": [{
      "name": "Team Nylas",
      "email": "tips@nylas.com"
    }],
    "reply_to": [{
      "name": "Team Nylas",
      "email": "tips@nylas.com"
    }],
    "headers": [
      {
        "name": "Delivered-To",
        "value": "nyla@example.com"
      },
      {
        "name": "Received",
        "value": "Thu, 21 Mar 2024 09:27:34 -0700 (PDT)"
      }
    ],
    "subject": "Upgrade to Nylas v3, now generally available",
    "body": "Nylas v3 is now generally available!",
    "snippet": "Nylas v3 is now generally available!",
    "unread": true
  }
}

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?

Email providers use the MIME format to represent the raw data of an email 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.

Using MIME data

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.

Request
Response (JSON)

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/?fields=raw_mime \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": {
    "grant_id": "<NYLAS_GRANT_ID>",
    "object": "message",
    "id": "<MESSAGE_ID>",
    "raw_mime": "<BASE64URL_ENCODED_STRING>"
  }
}

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.