Cabeçalhos e metadados

Esta página trata de duas formas de adicionar as suas próprias informações a um e-mail enviado com a API de e-mail: headers, que passam a fazer parte da mensagem que o destinatário recebe, e meta, que o Emailit armazena com o e-mail e devolve na API e nos webhooks. Ela também lista os cabeçalhos que o Emailit adiciona, reescreve ou remove.

Adicionar cabeçalhos personalizados

Passe headers como um objeto com nomes de cabeçalho e valores em string:

{
  "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 os campos da requisição, e não headers, para From, To, Cc, Bcc, Reply-To e Subject.
• Não defina cabeçalhos cujo nome comece com X-Emailit-. O Emailit os usa internamente. Por exemplo, uma mensagem que já contém X-Emailit-ID é tratada como processada e não passa pela reescrita de cabeçalhos nem pela assinatura DKIM do Emailit.
• Os cabeçalhos que o próprio Emailit define, como Message-ID e Date, são substituídos mesmo que você os envie. Consulte a próxima seção.

Cabeçalhos que o Emailit adiciona ou altera

O SMTP relay aplica a mesma reescrita às mensagens que você envia por SMTP.

Adicionar List-Unsubscribe a e-mails em massa

Provedores de e-mail como o Gmail e o Yahoo esperam uma opção de descadastro em um clique em e-mails promocionais e outros e-mails em massa. As campanhas adicionam uma automaticamente. Para newsletters ou resumos que você envia pela API, adicione você mesmo os dois cabeçalhos:

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

• A URL https deve aceitar uma requisição POST com o corpo List-Unsubscribe=One-Click e descadastrar a pessoa sem pedir confirmação (RFC 8058).
• Faça cada URL ser específica do destinatário, para que o seu endpoint saiba quem descadastrar.
• O Emailit inclui List-Unsubscribe e List-Unsubscribe-Post na assinatura DKIM, o que os provedores exigem para o descadastro em um clique.

Consulte Como atender aos requisitos do Gmail e do Yahoo para remetentes de grande volume? para conhecer os outros requisitos.

Quando alguém se descadastrar, pare de enviar para essa pessoa. Você pode adicioná-la à sua lista de supressão para que o Emailit bloqueie os envios futuros.

Anexar metadados

meta é um objeto com chaves e valores em string que o Emailit armazena com cada e-mail. Use-o para ligar um e-mail aos registros do seu próprio 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"
  }
}

Converta números e booleanos em strings antes de enviá-los. O Emailit devolve meta:

• Em Obter um e-mail, Obter os metadados e Listar e-mails.
• Nos eventos de webhook do e-mail: em data.object.meta para email.accepted, email.scheduled, email.canceled e os eventos de entrega, e em data.object.email.meta para email.loaded e email.clicked.

Um evento de entrega com metadados tem esta aparência (resumido):

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

Tentar enviar um e-mail de novo mantém os metadados dele. O encaminhamento cria um novo e-mail sem eles.

Encontrar e-mails depois

Não é possível pesquisar nem filtrar e-mails por meta. Para encontrar um e-mail de novo:

• Guarde os IDs. Salve o id, ou o mapa ids quando houver vários destinatários, junto ao seu próprio registro e consulte o e-mail com Obter um e-mail.
• Filtre a lista. Listar e-mails filtra por to, from, subject, status, created_at, updated_at, spam_score, api_key_id e sending_domain_id. Consulte Filtragem e ordenação.
• Use chaves de API separadas. Dê a cada aplicação ou funcionalidade a sua própria chave de API e filtre por api_key_id, ou por API key em Email API›Emails.
• Associe os eventos de webhook. Leia meta em cada evento para encaminhá-lo ao registro certo assim que ele chegar.

Veja também

• Enviar um e-mail
• Cabeçalhos SMTP
• Tipos de eventos de webhook
• Dicionário de cabeçalhos de e-mail