Plantillas

Una plantilla define el asunto y el cuerpo (HTML y/o texto plano) de los correos. Las campañas y sequences la referencian por id — puedes actualizar la plantilla sin tocar la campaña, y cambiar el contenido antes de enviar. Esto te permite iterar sobre el copy o el diseño sin tener que editar cada campaña por separado.

Esquema

Campo	Tipo	Descripción
id	string	Identificador slug de la plantilla.
name	string	Nombre descriptivo para identificarla en el dashboard.
subject	string	Asunto del correo. Admite merge tags.
html	string	Cuerpo en HTML. Admite merge tags.
body_text	string	Cuerpo en texto plano. Admite merge tags.
key_id	string	API key a la que pertenece.
created_at	string	Fecha de creación (ISO 8601).
updated_at	string	Fecha de última actualización (ISO 8601).

Merge tags

Puedes personalizar el asunto y el cuerpo usando {{name}} para insertar el nombre del contacto. MailerDash sustituye el tag en el momento del envío con el valor del campo name del contacto destinatario.

Ejemplo:

subject: "Hola {{name}}, tu reporte está listo"
html:    "<h1>Hola {{name}},</h1><p>Tu reporte del mes está disponible.</p>"

Si el contacto no tiene name, el tag se reemplaza por una cadena vacía.

También puedes usar cualquier campo de la metadata del contacto: si importaste una columna empresa, {{empresa}} funciona.

Tags de plataforma

Estos los genera MailerDash en el momento del envío, uno distinto por destinatario. No los puedes definir tú: si tu metadata trae un campo con uno de estos nombres, se ignora y gana el nuestro. El motivo es que llevan un token firmado que solo nosotros podemos emitir — un enlace de baja que apunta a otro lado es un correo que parece cumplir y no cumple.

Tag	Qué inserta
{{unsubscribe_url}}	Enlace de baja. Obligatorio: una plantilla sin él se rechaza con 400 al guardarla.
{{preferences_url}}	Centro de preferencias, para ajustar qué recibe en vez de irse del todo.
{{physical_address}}	Tu dirección postal. Requisito de CAN-SPAM.
{{reconfirm_url}}	Enlace de reconfirmación para campañas de re-engagement. Ver campañas.

El editor te avisa mientras trabajas si la plantilla no trae {{unsubscribe_url}} en ninguna parte —ni en el HTML, ni en el MJML, ni en el texto plano— para que no choques con el 400 cuando ya la diste por terminada. El aviso trae un botón «Agregar al pie» que lo inserta por ti: escribe sobre el campo que tenga contenido, y si tu plantilla es sólo texto plano agrega una línea legible en vez de inventarte un cuerpo HTML.

En el editor visual hay además un bloque «Pie legal» listo para arrastrar, con el enlace de baja y tu dirección postal — las dos cosas que pide CAN-SPAM §7704. La dirección va sólo en ese bloque, donde la ves y la puedes quitar, y no en lo que inserta el botón: si tu cuenta no la tiene cargada, te dejaría una línea vacía en el correo.

Consejo

Ofrecer el centro de preferencias junto a la baja reduce las bajas totales: quien solo quería menos correos no tiene que irse del todo para conseguirlo, que es justo el camino que termina en el botón de spam.

Operaciones

Listar plantillas

GET /v1/bulk/templates

Devuelve un array con todas las plantillas de tu cuenta.

---

Crear una plantilla

POST /v1/bulk/templates

Body:

{
  "name": "Bienvenida onboarding",
  "subject": "Bienvenido a bordo, {{name}}",
  "html": "<h1>Hola {{name}},</h1><p>Tu cuenta está lista.</p>",
  "body_text": "Hola {{name}},\n\nTu cuenta está lista."
}

name y subject son requeridos. Devuelve 201 con la plantilla creada.

---

Obtener una plantilla

GET /v1/bulk/templates/{id}

Devuelve todos los campos de la plantilla, incluyendo html y body_text.

---

Actualizar una plantilla

PATCH /v1/bulk/templates/{id}

Body (todos los campos son opcionales):

{
  "subject": "¡Bienvenido, {{name}}!",
  "html": "<h1>Hola {{name}},</h1><p>Tu cuenta está lista. Empieza ahora.</p>"
}

Devuelve 200 con la plantilla actualizada. Los campos que no envíes no se modifican.

---

Eliminar una plantilla

DELETE /v1/bulk/templates/{id}

Elimina la plantilla. Devuelve 204 No Content. Si está referenciada por una campaña activa, devuelve 409 Conflict.

---

Eliminar plantillas en lote

POST /v1/bulk/templates/delete

Eliminación atómica de múltiples plantillas. Body:

{ "ids": ["bienvenida-onboarding-abc", "promo-verano-xyz"] }

Respuesta:

{
  "requested": 2,
  "deleted": 1,
  "not_found": [],
  "forbidden": [],
  "in_use": ["promo-verano-xyz"]
}

Las plantillas en uso por campañas activas se reportan en in_use sin borrarse. Las demás sí se eliminan en el mismo request.

Ejemplo

Crear una plantilla con HTML y texto plano

curl -X POST https://api.mailerdash.com/v1/bulk/templates \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bienvenida onboarding",
    "subject": "Bienvenido a bordo, {{name}}",
    "html": "<h1>Hola {{name}},</h1><p>Tu cuenta está lista.</p>",
    "body_text": "Hola {{name}},\n\nTu cuenta está lista."
  }'

Consejo

Incluye siempre body_text junto con html. Los clientes de correo que no renderizan HTML — algunos corporativos y muchos clientes móviles en modo ahorro — muestran el texto plano como fallback. Además, tener ambas versiones mejora la reputación del remitente y ayuda a la deliverability.

Precaución

No puedes eliminar una plantilla referenciada por una campaña activa. El bulk delete reporta las plantillas in_use sin borrarlas — el resto sí se elimina. Para liberar una plantilla, cancela o completa primero las campañas que la usan.

Referencia

Para el esquema completo de request/response y códigos de error, consulta la referencia de API bulk.