Guía
Migrar desde Mailtrap
Pasa de Mailtrap Email Sending a Emailit. Equivalencias de streams, tokens y subcuentas, conversión de las llamadas a la API y de las plantillas Handlebars, cambio de SMTP, y traslado de webhooks, direcciones bloqueadas y contactos.
Esta guía relaciona los conceptos, las llamadas a la API, los webhooks, las direcciones bloqueadas, las plantillas y los contactos de Mailtrap Email Sending con sus equivalentes en Emailit. Lee primero Migrar a Emailit para conocer el orden general y cómo usar los dos proveedores en paralelo.
Conceptos
| Mailtrap | Emailit |
|---|---|
| Organización y subcuentas | Cuenta y espacios de trabajo. Cada espacio de trabajo tiene sus propios dominios, claves, miembros y créditos. |
| Dominios de envío | Dominios de envío |
| Stream transaccional | La API de email y el SMTP relay |
| Stream de envíos masivos | Campañas, o la API con tus propias cabeceras List-Unsubscribe |
| Tokens de API con permisos por recurso | Claves de API: Full Access, o Sending Only limitada opcionalmente a un dominio |
| Dominio de demostración | Los espacios de trabajo nuevos están en modo sandbox y pueden enviar a los miembros del espacio de trabajo desde tu propio dominio verificado. |
| Email Sandbox (pruebas) | No disponible. Conserva el sandbox de Mailtrap para las pruebas, o envía a los miembros del espacio de trabajo mientras desarrollas. |
| Plantillas | Plantillas con un alias y versiones, renderizadas con Temple |
| Webhooks por stream | Webhooks por espacio de trabajo |
| Suppressions por dominio y por stream | Una lista de direcciones bloqueadas por espacio de trabajo |
| Registros de emails | Email APIEmails y Email APILogs |
category y custom_variables |
meta |
| Email Marketing: contactos, listas, campañas, automatizaciones | Contactos, listas de contactos, campañas y automatizaciones (beta) |
| Emails entrantes | Emails entrantes |
Para mantener separadas la reputación transaccional y la de marketing, como hacen los dos streams de Mailtrap, envía cada tipo desde dominios o subdominios distintos, como mail.acme.com para los recibos y news.acme.com para las newsletters.
Actualizar las llamadas a la API
POST /api/send de Mailtrap pasa a ser POST /v2/emails. Los dos reciben un token bearer y JSON, pero en Emailit las direcciones son cadenas simples en lugar de objetos:
curl https://send.api.mailtrap.io/api/send \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "hello@acme.com", "name": "Acme" },
"to": [{ "email": "ada@example.com" }],
"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>"
}'| Mailtrap | Emailit |
|---|---|
Authorization: Bearer <token> o Api-Token: <token> |
Authorization: Bearer secret_… |
send.api.mailtrap.io y bulk.api.mailtrap.io |
Un único host, api.emailit.com |
from: { email, name } |
from: "Name <email>" |
to[], cc[], bcc[] con email y name |
to, cc, bcc como cadena o como array de hasta 50 cada uno |
reply_to: { email, name } |
reply_to |
subject, text, html, headers |
Igual |
attachments[] con content, filename, type, disposition y content_id |
attachments[] con content, filename, content_type y content_id, o una url en lugar de content |
category |
meta, por ejemplo meta: { "category": "password-reset" } |
custom_variables |
meta, que se devuelve en los eventos de webhook |
template_uuid y template_variables |
template (un alias o ID) y variables |
| Seguimiento configurado por dominio | Seguimiento configurado por dominio, o por email con tracking: { "loads": true, "clicks": true } |
POST /api/batch (hasta 500 mensajes) |
No disponible. Envía una petición por mensaje. |
Respuesta con message_ids, uno por destinatario |
200 con id (em_…), status: "accepted" y, con varios destinatarios, ids con un ID para cada uno |
Emailit también admite la programación con scheduled_at y los reintentos seguros con una cabecera Idempotency-Key, que la API de envío de Mailtrap no ofrece. Consulta Enviar un email.
Cambiar la configuración SMTP
| Ajuste | Mailtrap | Emailit |
|---|---|---|
| Host | live.smtp.mailtrap.io, o bulk.smtp.mailtrap.io para el stream de envíos masivos |
smtp.emailit.com |
| Puerto | 587, 2525 o 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 o 25 (STARTTLS), 465 (TLS) |
| Usuario | api |
emailit |
| Contraseña | Tu token de API de Mailtrap | Tu clave de API de Emailit |
Emailit no lee las cabeceras X-MT-Category ni X-MT-Custom-Variables. Elimínalas y usa la API cuando necesites metadatos. Consulta Configuración SMTP.
Equivalencias de los eventos de webhook
| Evento de Mailtrap | Evento de Emailit |
|---|---|
delivery |
email.delivered |
soft bounce |
email.attempted mientras Emailit reintenta, y después email.bounced si fallan todos los reintentos |
bounce |
email.bounced |
reject |
email.suppressed cuando la dirección tiene un bloqueo de tipo recipient |
suspension |
email.held |
spam |
email.complained |
open |
email.loaded |
click |
email.clicked |
unsubscribe |
email.unsubscribed, solo para los emails de campaña |
inbound.message_received |
email.received; después, obtén el contenido con GET /emails/{id} |
Emailit también envía email.accepted cuando la API acepta un email. Consulta Tipos de eventos.
El formato de las peticiones cambia:
- Mailtrap envía una lista
eventsde hasta 500 eventos, o JSON Lines. Emailit envía como cuerpo de la petición un array JSON de hasta 100 eventos. - El nombre del evento está en
typey el email, endata.object. Usadata.object.id, el IDem_de la respuesta de envío, en lugar demessage_id, ydata.object.toen lugar deemail. Tus valores demeta, que sustituyen acategoryycustom_variables, 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. - La cabecera
Mailtrap-Signaturede Mailtrap es un HMAC-SHA256 del cuerpo en bruto. La cabeceraX-Emailit-Signaturede Emailit es un HMAC-SHA256 de<timestamp>.<raw body>con tu secretowhsec_como clave, así que lee tambiénX-Emailit-Timestamp. 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 las direcciones bloqueadas desde Suppressions en Mailtrap, o recorre las páginas de
GET https://mailtrap.io/api/suppressions, que devuelve hasta 1000 entradas por llamada. -
Crea un único CSV con las columnas
email,type,reason:Tipo en Mailtrap Tipo en Emailit hard bounce,spam complaint,manual importrecipient, que bloquea los envíos por API, por SMTP y de campañasunsubscriptionunsubscribe, que detiene las campañas pero sigue dejando pasar los emails transaccionales. Usarecipientpara las bajas del stream transaccional.email,type,reason old-address@example.com,recipient,mailtrap hard bounce left@example.com,unsubscribe,mailtrap unsubscription -
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, así que las direcciones bloqueadas en varios dominios o streams de Mailtrap se añaden una sola vez.
Consulta Gestionar las direcciones bloqueadas.
Trasladar los contactos
Si usas Mailtrap Email Marketing, exporta tus contactos desde Contacts con More Actions > Export, o con POST https://mailtrap.io/api/contacts/exports filtrado por subscription_status y list_id. Antes, crea en Emailit los campos personalizados y las listas de contactos correspondientes.
Importa solo los contactos suscritos, una lista de contactos cada vez, en Email MarketingContacts con Import. La importación añade como suscritas a todas las personas del archivo, así que, en su lugar, añade los contactos dados de baja a tu archivo de direcciones bloqueadas con el tipo unsubscribe. Divide los archivos en partes de hasta 2500 filas. Consulta Importar y exportar contactos.
Trasladar las plantillas
Obtén el HTML de tus plantillas con GET https://mailtrap.io/api/email_templates, que devuelve el body_html, el body_text y el subject de cada plantilla. Importa cada una en Email MarketingTemplates o créala con la API de plantillas, y asígnale un alias, como receipt.
Las plantillas de Mailtrap usan Handlebars. Temple cubre lo más habitual:
| Mailtrap (Handlebars) | Emailit (Temple) |
|---|---|
{{name}}, {{user.name}} |
Igual |
{{{html_block}}} |
{{html_block}}. Temple nunca escapa el HTML, así que escapa tú los datos que introducen los usuarios. |
{{#if plan}}…{{else}}…{{/if}} |
Igual |
{{#unless plan}}…{{/unless}} |
{{#if plan}}{{else}}…{{/if}} |
{{#if name}}{{name}}{{else}}Customer{{/if}} |
{{name|"Customer"}} |
{{#each items}}…{{/each}}, {{#with}} |
No compatible. Genera la lista en tu código y pásala como una sola variable. |
template_variables |
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 los registros DKIM rwmt1._domainkey y rwmt2._domainkey de Mailtrap, su CNAME de verificación ni su CNAME de seguimiento mt-link. Conserva tu registro DMARC. Consulta Registros DNS de los dominios de envío.
Después del cambio definitivo, elimina los registros DKIM, de verificación y de seguimiento de Mailtrap, y quita include:_spf.mailtrap.io si tu registro SPF todavía lo tiene. Los emails entrantes de Mailtrap se reciben en el registro MX de tu dominio raíz, y los de Emailit en un subdominio como inbound.acme.com, así que traslada el correo entrante y actualiza tus direcciones de recepción antes de cambiar el registro MX. Consulta Configurar el email entrante.
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