Headers and metadata

This page covers two ways to add your own information to an email sent with the Email API: headers, which become part of the message the recipient gets, and meta, which Emailit stores with the email and returns in the API and in webhooks. It also lists the headers Emailit adds, rewrites or removes.

Add custom headers

Pass headers as an object of header names and string values:

{
  "from": "Acme <orders@acme.com>",
  "to": "ada@example.com",
  "subject": "Receipt for order 1042",
  "text": "Thanks for your order.",
  "headers": {
    "X-Entity-Ref-ID": "order-1042",
    "X-Acme-Account": "881"
  }
}

• Use the request fields, not headers, for From, To, Cc, Bcc, Reply-To and Subject.
• Don’t set headers whose names start with X-Emailit-. Emailit uses them internally. For example, a message that already contains X-Emailit-ID is treated as processed and skips Emailit’s header rewriting and DKIM signing.
• Headers that Emailit sets itself, such as Message-ID and Date, are replaced even if you send them. See the next section.

Headers Emailit adds or changes

The SMTP relay applies the same rewriting to messages you submit over SMTP.

Add List-Unsubscribe to bulk mail

Mailbox providers such as Gmail and Yahoo expect a one-click unsubscribe option on promotional and other bulk mail. Campaigns add one automatically. For newsletters or digests you send through the API, add both headers yourself:

{
  "from": "Acme <news@acme.com>",
  "to": "ada@example.com",
  "subject": "Acme weekly digest",
  "html": "<p>This week at Acme…</p>",
  "headers": {
    "List-Unsubscribe": "<https://acme.com/unsubscribe?u=881&l=digest>, <mailto:unsubscribe@acme.com?subject=unsubscribe-881>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

• The https URL must accept a POST request with the body List-Unsubscribe=One-Click and unsubscribe the person without asking them to confirm (RFC 8058).
• Make each URL specific to the recipient, so your endpoint knows who to unsubscribe.
• Emailit includes List-Unsubscribe and List-Unsubscribe-Post in the DKIM signature, which providers require for one-click unsubscribe.

See How do I meet Gmail and Yahoo bulk sender requirements? for the other requirements.

When someone unsubscribes, stop sending to them. You can add them to your suppression list so Emailit blocks future sends.

Attach metadata

meta is an object of string keys and string values that Emailit stores with each email. Use it to connect an email to records in your own system.

{
  "from": "Acme <orders@acme.com>",
  "to": "ada@example.com",
  "subject": "Receipt for order 1042",
  "text": "Thanks for your order.",
  "meta": {
    "order_id": "1042",
    "customer_id": "cus_881",
    "kind": "receipt"
  }
}

Convert numbers and booleans to strings before you send them. Emailit returns meta:

• In Retrieve an email, Retrieve metadata and List emails.
• In webhook events for the email: under data.object.meta for email.accepted, email.scheduled, email.canceled and the delivery events, and under data.object.email.meta for email.loaded and email.clicked.

A delivery event with metadata looks like this (trimmed):

[
  {
    "type": "email.delivered",
    "data": {
      "object": {
        "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
        "object": "email",
        "to": "ada@example.com",
        "subject": "Receipt for order 1042",
        "status": "delivered",
        "meta": { "order_id": "1042", "customer_id": "cus_881", "kind": "receipt" }
      }
    }
  }
]

Retrying an email keeps its metadata. Forwarding creates a new email without it.

Find emails later

You can’t search or filter emails by meta. To find an email again:

• Store the IDs. Save the id, or the ids map for several recipients, next to your own record, and look the email up with Retrieve an email.
• Filter the list. List emails filters on to, from, subject, status, created_at, updated_at, spam_score, api_key_id and sending_domain_id. See Filtering.
• Use separate API keys. Give each application or feature its own API key, then filter by api_key_id, or by API key in Email API›Emails.
• Match webhook events. Read meta from each event to route it to the right record as it arrives.

Related

• Send an email
• SMTP headers
• Webhook event types
• Email headers dictionary