Cabeceras y metadatos

Esta página trata dos formas de añadir tu propia información a un email enviado con la API de email: headers, que pasan a formar parte del mensaje que recibe el destinatario, y meta, que Emailit guarda con el email y devuelve en la API y en los webhooks. También lista las cabeceras que Emailit añade, reescribe o elimina.

Añadir cabeceras personalizadas

Pasa headers como un objeto con nombres de cabecera y valores de tipo cadena:

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

• Para From, To, Cc, Bcc, Reply-To y Subject, usa los campos de la petición, no headers.
• No definas cabeceras cuyo nombre empiece por X-Emailit-. Emailit las usa internamente. Por ejemplo, un mensaje que ya contiene X-Emailit-ID se trata como procesado y se salta la reescritura de cabeceras y la firma DKIM de Emailit.
• Las cabeceras que define el propio Emailit, como Message-ID y Date, se sustituyen aunque las envíes. Consulta la sección siguiente.

Cabeceras que Emailit añade o cambia

El SMTP relay aplica la misma reescritura a los mensajes que envías por SMTP.

Añadir List-Unsubscribe al correo masivo

Los proveedores de correo como Gmail y Yahoo esperan una opción de baja con un clic en el correo promocional y en el resto del correo masivo. Las campañas la añaden automáticamente. En las newsletters o los resúmenes que envías con la API, añade tú las dos cabeceras:

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

• La URL https debe aceptar una petición POST con el cuerpo List-Unsubscribe=One-Click y dar de baja a la persona sin pedirle confirmación (RFC 8058).
• Haz que cada URL sea específica del destinatario, para que tu endpoint sepa a quién dar de baja.
• Emailit incluye List-Unsubscribe y List-Unsubscribe-Post en la firma DKIM, algo que los proveedores exigen para la baja con un clic.

Para los demás requisitos, consulta ¿Cómo cumplo los requisitos de Gmail y Yahoo para remitentes masivos?.

Cuando alguien se da de baja, deja de enviarle correo. Puedes añadirlo a tu lista de direcciones bloqueadas para que Emailit bloquee los envíos futuros.

Adjuntar metadatos

meta es un objeto con claves y valores de tipo cadena que Emailit guarda con cada email. Úsalo para vincular un email a los registros de tu propio 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"
  }
}

Convierte los números y los booleanos en cadenas antes de enviarlos. Emailit devuelve meta:

• En Obtener un email, Obtener los metadatos y Listar emails.
• En los eventos de webhook del email: en data.object.meta para email.accepted, email.scheduled, email.canceled y los eventos de entrega, y en data.object.email.meta para email.loaded y email.clicked.

Un evento de entrega con metadatos tiene este aspecto (abreviado):

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

Reintentar un email conserva sus metadatos. Reenviarlo crea un email nuevo sin ellos.

Encontrar emails más tarde

No puedes buscar ni filtrar emails por meta. Para volver a encontrar un email:

• Guarda los ID. Guarda el id, o el mapa ids si hay varios destinatarios, junto a tu propio registro, y busca el email con Obtener un email.
• Filtra la lista. Listar emails filtra por to, from, subject, status, created_at, updated_at, spam_score, api_key_id y sending_domain_id. Consulta Filtrado.
• Usa claves de API separadas. Da a cada aplicación o función su propia clave de API, y después filtra por api_key_id, o por API key en Email API›Emails.
• Asocia los eventos de webhook. Lee meta en cada evento para dirigirlo al registro correcto en cuanto llega.

Ver también

• Enviar un email
• Cabeceras SMTP
• Tipos de eventos de webhook
• Diccionario de cabeceras de email