Plantillas

Cree plantillas de correo electrónico reutilizables con variables dinámicas. Las plantillas almacenan el asunto, el contenido HTML y el contenido de texto de su correo electrónico para que pueda enviar correos personalizados sin reconstruir el contenido en cada solicitud.

Crear una plantillaCopiar enlace de la sección

POST https://api.mail.land/v1/templates

curl -X POST https://api.mail.land/v1/templates \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation",
    "subject": "Your order #{{orderNumber}} is confirmed",
    "htmlContent": "<h1>Thanks, {{firstName}}!</h1><p>Order #{{orderNumber}} has been confirmed. Total: {{total}}</p>",
    "textContent": "Thanks, {{firstName}}! Order #{{orderNumber}} has been confirmed. Total: {{total}}",
    "categoryId": "k3v9q2m7xw4tpa"
  }'

{
  "id": "t8x2m4q9zk7wpr",
  "name": "Order Confirmation",
  "subject": "Your order #{{orderNumber}} is confirmed",
  "htmlContent": "<h1>Thanks, {{firstName}}!</h1>...",
  "textContent": "Thanks, {{firstName}}!...",
  "categoryId": "k3v9q2m7xw4tpa",
  "categoryName": "Transactional",
  "categoryColor": "#3B82F6",
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": null
}

Reglas de validaciónCopiar enlace de la sección

Sintaxis de variablesCopiar enlace de la sección

Use llaves dobles para la sustitución de variables:

<h1>Hello {{firstName}},</h1>
<p>Your order #{{orderNumber}} shipped on {{shipDate}}.</p>
<p>Track your package: <a href="{{trackingUrl}}">{{trackingNumber}}</a></p>

Las variables se sustituyen en el momento del envío. Pase los valores a través del campo variables en su solicitud de envío:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345",
        "shipDate": "Feb 17, 2026",
        "trackingUrl": "https://track.example.com/ABC123",
        "trackingNumber": "ABC123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr"
}

Valores predeterminadosCopiar enlace de la sección

Una plantilla puede llevar un valor predeterminado para cada campo de contacto que usa, de modo que un suscriptor sin valor en ese campo reciba igualmente el correo. Defínalos con variableDefaults, un objeto de nombre de marcador a valor, al crear y al actualizar. También se devuelven al obtener, listar o duplicar una plantilla.

{
  "name": "Welcome",
  "subject": "Hello {{firstName}}",
  "htmlContent": "<p>Hi {{firstName}}</p>",
  "variableDefaults": { "firstName": "cliente" }
}

Reglas:

• Los valores predeterminados se aplican solo a los envíos de campañas y automatizaciones. El valor propio no vacío del destinatario siempre prevalece sobre el predeterminado.
• Un campo sin valor ni predeterminado se sigue rechazando: MailLand nunca envía un {{firstName}} literal.
• Los envíos transaccionales por API y SMTP no se ven afectados. Allí los valores vienen de su solicitud, y uno que falta se rechaza como se describió arriba.
• Al actualizar, omitir variableDefaults conserva los valores guardados. Envíe {} para borrarlos.
• Los nombres siguen la sintaxis de los marcadores. email y subscriberId siempre se suministran y no admiten valor predeterminado. Un valor es una línea de 200 caracteres como máximo, y una plantilla tiene como máximo 50 valores predeterminados.

En el editor del panel, cada marcador tiene un campo de valor predeterminado que muestra cuántos suscriptores no tienen ese campo, y al guardar se le avisa si un campo que falta a algunos suscriptores no tiene valor predeterminado.

Vista previa de una plantillaCopiar enlace de la sección

Previsualice una plantilla con valores de muestra rellenados automáticamente para las variables detectadas:

GET https://api.mail.land/v1/templates/{id}/preview

curl https://api.mail.land/v1/templates/t8x2m4q9zk7wpr/preview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "id": "t8x2m4q9zk7wpr",
  "name": "Order Confirmation",
  "subject": "Your order #12345 is confirmed",
  "renderedHtml": "<h1>Thanks, John!</h1><p>Order #12345 has been confirmed.</p>",
  "renderedText": "Thanks, John! Order #12345 has been confirmed."
}

Duplicar una plantillaCopiar enlace de la sección

Clone una plantilla existente:

POST https://api.mail.land/v1/templates/{id}/duplicate

curl -X POST https://api.mail.land/v1/templates/t8x2m4q9zk7wpr/duplicate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

El duplicado recibe un nombre generado automáticamente: "Order Confirmation (Copy)". Si ya existe una copia, el nombre se incrementa: "Order Confirmation (Copy 2)", etc.

Categorías de plantillasCopiar enlace de la sección

Organice las plantillas en categorías con colores opcionales.

Crear una categoríaCopiar enlace de la sección

POST https://api.mail.land/v1/templates/categories

curl -X POST https://api.mail.land/v1/templates/categories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transactional",
    "description": "Order confirmations, receipts, and shipping notifications",
    "color": "#3B82F6"
  }'

Listar categoríasCopiar enlace de la sección

GET https://api.mail.land/v1/templates/categories

curl https://api.mail.land/v1/templates/categories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "categories": [
    {
      "id": "k3v9q2m7xw4tpa",
      "name": "Transactional",
      "description": "Order confirmations, receipts",
      "color": "#3B82F6",
      "templateCount": 12,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "totalCount": 3
}

Listar plantillasCopiar enlace de la sección

GET https://api.mail.land/v1/templates?limit=50

curl "https://api.mail.land/v1/templates?limit=50" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Filtrar por categoría:

GET https://api.mail.land/v1/templates?categoryId=k3v9q2m7xw4tpa

curl "https://api.mail.land/v1/templates?categoryId=k3v9q2m7xw4tpa" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    {
      "id": "t8x2m4q9zk7wpr",
      "name": "Order Confirmation",
      "subject": "Your order #{{orderNumber}} is confirmed",
      "htmlContent": "...",
      "categoryName": "Transactional",
      "categoryColor": "#3B82F6",
      "createdAt": "2026-02-17T10:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Actualizar una plantillaCopiar enlace de la sección

PUT https://api.mail.land/v1/templates/{id}

Todos los campos son obligatorios en la solicitud de actualización (es un reemplazo completo, no una actualización parcial):

curl -X PUT https://api.mail.land/v1/templates/t8x2m4q9zk7wpr \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation v2",
    "subject": "Order #{{orderNumber}} confirmed - {{companyName}}",
    "htmlContent": "<h1>Thanks, {{firstName}}!</h1><p>Updated template content.</p>",
    "textContent": "Thanks, {{firstName}}! Updated template content.",
    "categoryId": "k3v9q2m7xw4tpa"
  }'

Eliminar una plantillaCopiar enlace de la sección

DELETE https://api.mail.land/v1/templates/{id}

curl -X DELETE https://api.mail.land/v1/templates/t8x2m4q9zk7wpr \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Devuelve 204 No Content en caso de éxito. Una plantilla eliminada ya no puede recuperarse, listarse ni usarse para enviar: una solicitud de envío que la referencie, inmediata o programada, se rechaza con 400 TEMPLATE_NOT_FOUND, y una programación cuya plantilla se elimina antes de su hora prevista se rechaza de la misma forma en el momento del envío.

Uso de plantillas al enviarCopiar enlace de la sección

Haga referencia a una plantilla por su ID en su solicitud de envío. El asunto y el contenido de la plantilla se utilizan con las variables sustituidas:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

Cuando se establece templateId, siempre se usa el asunto renderizado de la plantilla; cualquier subject en la solicitud de envío se ignora.

Límites del planCopiar enlace de la sección

El número de plantillas que puede crear depende de su plan. Si alcanza el límite, crear una nueva plantilla devuelve 403 PLAN_LIMIT_REACHED.

Pasos siguientesCopiar enlace de la sección

• REST API: enviar correos con plantillas
• Envío por lotes: usar plantillas con correos en lote
• Correos programados: usar plantillas mediante /v1/transactional/send con scheduledAt (el endpoint de programación no tiene campo templateId)