Guía
Migrar desde SparkPost
Pasa de SparkPost (ahora Bird Email) a Emailit. Conversión de las transmissions y de los datos de sustitución, cambio de la configuración SMTP_Injection, y traslado de los webhooks de eventos, las direcciones bloqueadas, las plantillas y los DNS.
Esta guía relaciona los conceptos, las llamadas a la API, los webhooks, las direcciones bloqueadas y las plantillas de SparkPost con sus equivalentes en Emailit. SparkPost ahora forma parte de Bird y se vende como Bird Email, y la API de SparkPost en api.sparkpost.com sigue funcionando. Esta guía trata esa API. Lee primero Migrar a Emailit para conocer el orden general y cómo usar los dos proveedores en paralelo.
Conceptos
| SparkPost | Emailit |
|---|---|
| Cuenta principal y subcuentas | Cuenta y espacios de trabajo. Cada espacio de trabajo tiene sus propios dominios, claves, miembros y créditos. |
| Cuentas de EE. UU. y de la UE, con hosts de API distintos | Un solo host de API, api.emailit.com |
| Claves de API con permisos | Claves de API: Full Access, o Sending Only limitada opcionalmente a un dominio |
| Dominios de envío | Dominios de envío |
| Bounce domains | El return-path emailit.<your domain>, que tienen todos los dominios |
| Dominios de seguimiento | Subdominio de seguimiento, como go.acme.com |
| Transmissions | Emails, una petición por mensaje |
| Listas de destinatarios guardadas | Listas de contactos y campañas |
| Plantillas y snippets | Plantillas con un alias y versiones. No hay snippets. |
| Webhooks de eventos | Webhooks |
| Dominios de entrada y relay webhooks | Emails entrantes |
| Lista de suppressions | Direcciones bloqueadas |
metadata, tags, campaign_id |
meta |
options.sandbox |
No hay modo de prueba. Los espacios de trabajo nuevos están en modo sandbox y solo entregan a los miembros del espacio de trabajo. |
| Pools de IP | IP dedicadas bajo solicitud |
Actualizar las llamadas a la API
POST /api/v1/transmissions de SparkPost pasa a ser POST /v2/emails. El contenido pasa al nivel superior, y los destinatarios pasan a ser to, cc y bcc:
curl https://api.sparkpost.com/api/v1/transmissions \
-H "Authorization: $SPARKPOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipients": [{ "address": { "email": "ada@example.com" } }],
"content": {
"from": { "email": "hello@acme.com", "name": "Acme" },
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}
}'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",
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}'| SparkPost | Emailit |
|---|---|
Authorization: <API key>, sin Bearer |
Authorization: Bearer secret_… |
content.from, una cadena o { email, name } |
from: "Name <email>" |
recipients[].address |
to, una cadena o un array de hasta 50 direcciones |
CC y CCO como destinatarios adicionales con header_to y una cabecera CC |
cc y bcc |
content.reply_to |
reply_to |
content.subject, content.text, content.html |
subject, text, html |
content.headers |
headers |
content.attachments[] con name, type, data |
attachments[] con filename, content_type, content |
content.inline_images[] |
attachments[] con un content_id, al que se hace referencia como cid: en el HTML |
content.template_id |
template: un alias envía la versión publicada, y un ID tem_ envía exactamente esa versión, sea un borrador o no |
substitution_data |
variables |
metadata, recipients[].tags, campaign_id |
meta, un objeto de valores de cadena que se devuelve en los eventos de webhook |
options.open_tracking, options.click_tracking |
tracking: { "loads": true, "clicks": true } |
options.start_time (con hasta 3 días de antelación) |
scheduled_at (ISO 8601 o lenguaje natural en inglés) |
options.transactional |
No es necesario. Los emails de la API nunca llevan cabeceras List-Unsubscribe, salvo que las añadas tú. |
content.email_rfc822 |
Envía el mensaje MIME a través del SMTP relay |
recipients: { "list_id": "…" } |
Una campaña a una lista de contactos |
Cabecera Idempotency-Key |
Cabecera Idempotency-Key, que se conserva durante 24 horas |
Respuesta con el id de la transmission y el recuento de destinatarios |
200 con id (em_…), status: "accepted" y, con varios destinatarios, ids con un ID para cada uno |
SparkPost envía un mensaje independiente a cada destinatario de una transmission, y nadie ve las demás direcciones. En Emailit, todas las direcciones de to y cc aparecen en las cabeceras de cada copia. Para mantener separados a los destinatarios, o para dar a cada uno sus propios substitution_data, envía una petición por destinatario. Obtienes los ID de los emails de inmediato, en lugar de buscar los ID de los mensajes en eventos posteriores. Consulta Enviar un email.
Cambiar la configuración SMTP
| Ajuste | SparkPost | Emailit |
|---|---|---|
| Host | smtp.sparkpostmail.com o smtp.eu.sparkpostmail.com |
smtp.emailit.com |
| Puerto | 587 o 2525 (STARTTLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Usuario | SMTP_Injection |
emailit |
| Contraseña | Una clave de API con el permiso Send via SMTP | Tu clave de API de Emailit |
Emailit no lee la cabecera X-MSYS-API. Elimínala. Pon las direcciones en CC y CCO en el mensaje como destinatarios normales, configura el seguimiento en el dominio y usa la API cuando necesites metadatos. Consulta Configuración SMTP.
Equivalencias de los eventos de webhook
| Evento de SparkPost | Evento de Emailit |
|---|---|
injection |
email.accepted (solo API) |
delivery |
email.delivered |
delay |
email.attempted |
bounce, out_of_band |
email.bounced |
policy_rejection |
email.suppressed cuando la dirección tiene un bloqueo de tipo recipient |
generation_failure, generation_rejection |
Ningún evento. Los problemas como una plantilla desconocida son errores en la respuesta de la API. |
spam_complaint |
email.complained |
open, initial_open |
email.loaded |
click |
email.clicked |
list_unsubscribe, link_unsubscribe |
email.unsubscribed, solo para los emails de campaña |
| Relay webhook | email.received; después, obtén el contenido con GET /emails/{id} |
El formato de las peticiones cambia:
- Los dos envían por POST un array JSON de eventos. SparkPost envuelve cada evento en
msysy en una clase comomessage_event. Emailit pone el nombre entypey el email endata.object, con hasta 100 eventos por petición. - Usa
data.object.id, el IDem_de la respuesta de envío, en lugar demessage_idytransmission_id, ydata.object.toen lugar dercpt_to. Tus valores demeta, que sustituyen arcpt_metayrcpt_tags, están endata.object.meta. - Para
email.loadedyemail.clicked,data.objectes la carga o el clic. Usadata.object.email_idpara el ID del email, ydata.object.email.rcpt_toydata.object.email.metapara el destinatario y tus valores demeta. - SparkPost protege los webhooks con autenticación básica u OAuth 2.0, sin firma. Emailit firma todas las peticiones: verifica
X-Emailit-SignatureconX-Emailit-Timestampy tu secretowhsec_. Consulta Verificar las firmas de los webhooks.
for (const event of req.body) {
const email = event.data.object;
if (event.type === 'email.bounced') markBounced(email.to, email.id);
if (event.type === 'email.complained') unsubscribe(email.to);
}Trasladar las direcciones bloqueadas
-
Exporta la lista de suppressions con
GET /api/v1/suppression-list?per_page=10000&cursor=initialy sigue el cursor hasta tener todas las páginas. Incluye las entradas de tus subcuentas, cada una con susubaccount_id. -
Crea un único CSV con las columnas
email,type,reason:Entrada de SparkPost Tipo en Emailit transactional, o los dos tiposrecipient, que bloquea los envíos por API, por SMTP y de campañasSolo non_transactionalunsubscribe, que detiene las campañas pero sigue dejando pasar los emails transaccionalesopen_trackingDéjala fuera. No bloquea los envíos. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
En Email APISuppressions, selecciona Import y sube el archivo. Cada archivo puede tener hasta 10.000 filas y ocupar como máximo 8 MB. Los duplicados se omiten.
Si usabas subcuentas, divide el archivo por subcuenta e importa cada parte en el espacio de trabajo correspondiente. Consulta Gestionar las direcciones bloqueadas.
Trasladar las plantillas
Obtén cada plantilla publicada con GET /api/v1/templates/{id}?draft=false, que devuelve content.html, content.text y content.subject. Impórtala en Email MarketingTemplates o créala con la API de plantillas, y usa el ID de la plantilla de SparkPost como alias si se ajusta al formato de los alias: letras minúsculas, números, - y _.
Convierte el lenguaje de plantillas de SparkPost a Temple:
| SparkPost | Emailit (Temple) |
|---|---|
{{name}}, {{order.total}} |
Igual |
{{address.name}}, {{address.email}} (el destinatario) |
Pásalos en variables, por ejemplo como name y email |
{{{html_block}}} |
{{html_block}}. Temple nunca escapa el HTML, así que escapa tú los datos que introducen los usuarios. |
{{name or 'Customer'}} |
{{name|"Customer"}} |
{{if plan}}…{{else}}…{{end}} |
{{#if plan}}…{{else}}…{{/if}} |
{{if plan == 'pro'}}, {{elseif}}, and, or |
No compatible. Pasa un booleano como is_pro y usa {{#if is_pro}}. |
{{each items}}…{{end}} |
No compatible. Genera la lista en tu código y pásala como una sola variable. |
render_snippet(), render_dynamic_content() |
No compatible. Pon el contenido en la plantilla o pásalo como una variable. |
substitution_data |
variables |
Consulta Lenguaje de plantillas Temple e Importar, exportar y duplicar plantillas.
Cambiar los DNS
Añade tu dominio en Email APIDomains y publica los registros de Emailit. Usan sus propios nombres (emailit._domainkey, emailit.<domain> y, opcionalmente, go e inbound), así que no entran en conflicto con el registro DKIM de SparkPost (un selector como scph0316._domainkey) ni con los CNAME de su bounce domain y de su dominio de seguimiento. Conserva tu registro DMARC. Consulta Registros DNS de los dominios de envío.
Si el dominio de seguimiento o el dominio de entrada de SparkPost ya usa el nombre go o inbound, elige otros nombres para Emailit con tracking_key e inbound_key. Consulta Configurar un dominio de seguimiento personalizado y Configurar el email entrante.
Después del cambio definitivo, elimina los registros DKIM, de rebote y de seguimiento de SparkPost. Si recibes correo con relay webhooks, trasládalo antes a un subdominio de entrada de Emailit y después elimina los registros MX rx1, rx2 y rx3 de SparkPost.
Próximos pasos
- Lista de comprobación para pasar a producción
- Configurar un webhook
- Migración prioritaria: deja que los ingenieros de Emailit hagan la migración contigo