Enviar un email

Esta guía explica cada parte de una petición POST /emails y lo que Emailit hace con ella, desde la dirección From hasta los errores que puedes recibir. Para la referencia completa de parámetros, consulta Enviar un email en la referencia de la API.

Antes de empezar

• Un dominio de envío verificado en tu espacio de trabajo. Consulta Añadir un dominio.
• Una clave de API con el permiso Full Access o Sending Only. Consulta Claves de API.
• Acceso de producción si envías a alguien que no sea miembro de tu espacio de trabajo. Consulta Acceso de producción.
• Créditos suficientes para todos los destinatarios (1 crédito cada uno).

Enviar un email básico

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);

Definir la dirección From

from es obligatorio y admite una dirección en cualquiera de estas formas:

• billing@acme.com
• Acme Billing <billing@acme.com>, o con comillas, "Acme, Inc." <billing@acme.com>

El dominio que sigue a la @ debe ser un dominio de envío verificado en el mismo espacio de trabajo:

• La coincidencia es exacta. Los dominios se comparan sin distinguir mayúsculas y minúsculas, pero mail.acme.com y acme.com son dominios distintos. Añade y verifica cada subdominio desde el que envíes.
• Cualquier parte local sirve. No necesitas un buzón para billing@ o no-reply@.
• Los dominios pendientes no pueden enviar. Un dominio que todavía espera la revisión (Pending verification) se trata como no verificado.
• Las claves limitadas se quedan en su dominio. Una clave Sending Only limitada a un dominio solo puede enviar desde ese dominio.
• Los dominios pausados están bloqueados. Si la salud de envío ha pausado el dominio, los envíos desde él se rechazan hasta que se levante la pausa.

Añadir destinatarios

to es obligatorio. cc y bcc son opcionales. Cada campo acepta una cadena o un array de cadenas, con o sin nombre visible, y admite hasta 50 direcciones. Una cadena puede contener varias direcciones separadas por comas; usa un array cuando el propio nombre visible contenga una coma.

Emailit elimina los duplicados entre to, cc y bcc (sin distinguir mayúsculas y minúsculas) y después crea un email por destinatario único, cada uno con su propio ID em_. Todas las copias llevan las mismas cabeceras To y Cc, así que los destinatarios ven la conversación como siempre, y los destinatarios de Bcc no aparecen nunca en las cabeceras de ninguna copia.

Cuando una petición tiene más de un destinatario, la respuesta incluye un mapa ids que asocia cada destinatario con el ID de su email. id es el email del primer destinatario.

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}

Cada destinatario cuesta 1 crédito y cuenta para tus límites de velocidad. Un destinatario con un bloqueo de tipo recipient se acepta y después se marca como suppressed en lugar de entregarse.

Escribir el contenido

Si reply_to indica la misma dirección que from, Emailit quita la cabecera Reply-To, porque no aporta nada y algunos filtros de spam la penalizan.

Enviar con una plantilla

Pon en template un alias de plantilla o un ID tem_, y pasa variables para los marcadores de Temple que contenga.

• Un alias envía la versión publicada en ese momento para ese alias. Si no hay ninguna versión publicada, la petición falla con 404.
• Un ID tem_ envía exactamente esa versión, esté publicada o no. Úsalo para probar una versión en borrador antes de publicarla.

Los campos de la petición tienen prioridad sobre la plantilla: un subject, html o text que envíes sustituye al valor de la plantilla. Si no envías reply_to, se usa el Reply-To de la plantilla. from siempre es obligatorio en la petición. Para saber cómo funciona la publicación, consulta Versiones de plantilla.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);

variables también funciona sin plantilla: Emailit renderiza los marcadores de Temple del subject, el html y el text que envías directamente en la petición.

Controlar el seguimiento

Por defecto, cada email sigue la configuración Track loads y Track clicks de su dominio de envío. Puedes cambiarla para cada email con tracking:

• "tracking": true o false activa o desactiva a la vez el seguimiento de cargas (aperturas) y de clics.
• "tracking": { "loads": true, "clicks": false } define cada uno por separado.

El seguimiento solo funciona cuando el CNAME de seguimiento del dominio está verificado. Sin él, el email se envía sin seguimiento y la petición se completa igualmente. El objeto tracking de la respuesta muestra la configuración que se ha aplicado realmente. Consulta Seguimiento de aperturas y clics.

Añadir cabeceras y metadatos

Usa headers para las cabeceras de email personalizadas, como List-Unsubscribe, y meta para tus propios pares clave-valor de tipo cadena. Emailit guarda meta con el email y lo incluye en los eventos de webhook. Consulta Cabeceras y metadatos.

Para adjuntar archivos, programar el envío o hacer que los reintentos sean seguros, consulta Adjuntos, Programación e Idempotencia.

Leer la respuesta

Una petición correcta devuelve 200:

Guarda el id (o el mapa ids) para poder asociar después los eventos de webhook y buscar el email con Obtener un email.

Eventos

El email de cada destinatario emite sus propios eventos:

1. email.accepted justo después de la petición, o email.scheduled si tiene una hora de envío futura.
2. Eventos de entrega a medida que el email avanza por el proceso de entrega: email.delivered, email.attempted (fallo temporal, se reintentará), email.bounced, email.failed, email.rejected o email.suppressed. Un email retenido para revisión emite email.held.
3. Eventos de interacción, si el seguimiento está activado: email.loaded y email.clicked. Las quejas por spam emiten email.complained.

Para saber qué significa cada estado, consulta Estados de los emails.

Errores

Los errores de validación devuelven una lista con todos los problemas encontrados:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}

Un espacio de trabajo suspendido recibe 403 con Workspace is suspended en cada envío. Para el formato general de los errores, consulta Errores.

Ver también

• Referencia de la API: Enviar un email
• Plantillas
• Estados de los emails
• Tipos de eventos de webhook
• ¿Por qué no ha llegado mi email?