Header e metadati

Questa pagina spiega due modi per aggiungere informazioni tue a un’email inviata con l’API email: headers, che entrano a far parte del messaggio ricevuto dal destinatario, e meta, che Emailit salva con l’email e restituisce nell’API e nei webhook. Elenca anche gli header che Emailit aggiunge, riscrive o rimuove.

Aggiungi header personalizzati

Passa headers come oggetto con i nomi degli header e valori di tipo stringa:

{
  "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"
  }
}

• Per From, To, Cc, Bcc, Reply-To e Subject usa i campi della richiesta, non headers.
• Non impostare header il cui nome inizia con X-Emailit-. Emailit li usa internamente. Ad esempio, un messaggio che contiene già X-Emailit-ID viene considerato già elaborato e salta la riscrittura degli header e la firma DKIM di Emailit.
• Gli header che imposta Emailit stesso, come Message-ID e Date, vengono sostituiti anche se li invii. Vedi la sezione successiva.

Header che Emailit aggiunge o modifica

L’SMTP relay applica la stessa riscrittura ai messaggi che invii tramite SMTP.

Aggiungi List-Unsubscribe alla posta di massa

I provider di posta come Gmail e Yahoo si aspettano un’opzione di disiscrizione con un clic nella posta promozionale e nelle altre email di massa. Le campagne la aggiungono automaticamente. Per le newsletter o i riepiloghi che invii tramite l’API, aggiungi tu entrambi gli header:

{
  "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"
  }
}

• L’URL https deve accettare una richiesta POST con il corpo List-Unsubscribe=One-Click e disiscrivere la persona senza chiederle conferma (RFC 8058).
• Rendi ogni URL specifico per il destinatario, così il tuo endpoint sa chi disiscrivere.
• Emailit include List-Unsubscribe e List-Unsubscribe-Post nella firma DKIM, come richiesto dai provider per la disiscrizione con un clic.

Vedi Come soddisfo i requisiti di Gmail e Yahoo per i mittenti di grandi volumi? per gli altri requisiti.

Quando qualcuno si disiscrive, smetti di inviargli email. Puoi aggiungerlo alla lista di soppressione, così Emailit blocca gli invii futuri.

Allega metadati

meta è un oggetto con chiavi e valori di tipo stringa che Emailit salva con ogni email. Usalo per collegare un’email ai record del tuo sistema.

{
  "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"
  }
}

Converti numeri e booleani in stringhe prima di inviarli. Emailit restituisce meta:

• In Recupera un’email, Recupera i metadati ed Elenca le email.
• Negli eventi webhook dell’email: in data.object.meta per email.accepted, email.scheduled, email.canceled e gli eventi di consegna, e in data.object.email.meta per email.loaded ed email.clicked.

Un evento di consegna con metadati ha questo aspetto (abbreviato):

[
  {
    "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" }
      }
    }
  }
]

Un nuovo tentativo mantiene i metadati dell’email. L’inoltro crea una nuova email senza metadati.

Ritrova le email in seguito

Non puoi cercare o filtrare le email per meta. Per ritrovare un’email:

• Salva gli ID. Salva l’id, o la mappa ids se i destinatari sono più di uno, accanto al tuo record, e recupera l’email con Recupera un’email.
• Filtra l’elenco. Elenca le email filtra per to, from, subject, status, created_at, updated_at, spam_score, api_key_id e sending_domain_id. Vedi Filtri e ordinamento.
• Usa chiavi API separate. Assegna a ogni applicazione o funzione la propria chiave API, poi filtra per api_key_id, o per API key in Email API›Emails.
• Associa gli eventi webhook. Leggi meta da ogni evento per indirizzarlo al record giusto appena arriva.

Vedi anche

• Invia un’email
• Header SMTP
• Tipi di evento
• Dizionario degli header email