Using email headers and MIME data

The Nylas Email API allows you to work with message 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 <[email protected]>
Reply-To: [email protected]
To: [email protected]
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 custom 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.

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

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "grant_id": "<NYLAS_GRANT_ID>",
    "object": "message",
    "id": "<MESSAGE_ID>",
    "thread_id": "<THREAD_ID>",
    "date": 1635355739,
    "to": [{
      "name": "Leyah Miller",
      "email": "[email protected]"
    }],
    "cc": [{
      "name": "Kaveh",
      "email": "[email protected]"
    }],
    "bcc": [],
    "from": [{
      "name": "Nyla",
      "email": "[email protected]"
    }],
    "reply_to": [{
      "name": "Nyla",
      "email": "[email protected]"
    }],
    "folders": ["INBOX"],
    "attachments": [],
    "headers": [
      {
        "name": "Delivered-To",
        "value": "[email protected]"
      },
      {
        "name": "Received",
        "value": "Thu, 21 Mar 2024 09:27:34 -0700 (PDT)"
      }
    ],
    "subject": "Reminder: Annual Philosophy Club Meeting",
    "body": "Don't forget, we're meeting on Thursday!",
    "snippet": "Don't forget, we're meeting on Thursday!",
    "starred": false,
    "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 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

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.

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

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

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 <[email protected]>
To: receiver <[email protected]>
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--"'