matumailer

SDK oficial de MatuMailer para enviar correos transaccionales desde Node.js.

Requisitos previos

1. Cuenta y proyecto en el dashboard.
2. Dominio verificado para envío (SPF + DKIM en DNS) y al menos un alias activo (ej. [email protected]).
3. Token de API (mm_live_...) generado en el proyecto.

El campo from debe ser un alias registrado y activo, no cualquier dirección del dominio. Si tienes un solo alias (o uno marcado como default), puedes omitir from.

Instalación

npm install matumailer

Configuración

import { MatuMailer } from 'matumailer';

const mail = new MatuMailer({
  token: process.env.MATUMAILER_TOKEN!,
  // MatuByte: https://matumailer.matubyte.com
  // MatuCatalogo (default npm): https://api.matucatalogo.com
  baseUrl: process.env.MATUMAILER_API_URL,
});

| Variable | Descripción | | -------------------- | ----------------------------------------- | | MATUMAILER_TOKEN | Token de API del proyecto (mm_live_...) | | MATUMAILER_API_URL | URL base de la API, sin /api (opcional) |

Identidades de envío (aliases)

// Ver qué direcciones puedes usar como `from`
const { identities } = await mail.sendingIdentities.list();
console.log(identities.map((i) => i.email));

// Enviar con alias explícito
await mail.send({
  to: '[email protected]',
  from: '[email protected]',
  fromName: 'Agenda', // opcional
  subject: 'Confirmación',
  html: '<p>Tu cita está confirmada.</p>',
});

// O con aliasId (UUID)
await mail.send({
  to: '[email protected]',
  aliasId: 'uuid-del-alias',
  subject: 'Hola',
  html: '<p>...</p>',
});

listAliases() y listDomains() funcionan con token API. Crear dominios/aliases requiere sesión del dashboard (JWT), no mm_live_.

Correo libre (HTML propio)

await mail.send({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Asunto',
  html: '<h1>Hola</h1>',
  text: 'Versión texto (opcional)',
  replyTo: '[email protected]',
  cc: ['[email protected]'],
});

Varios destinatarios: to: ['[email protected]', '[email protected]'] (un correo por persona).

Plantillas

await mail.sendTemplate('[email protected]', 'bienvenida', {
  nombre: 'Ana',
  codigo: '12345',
});

await mail.send({
  to: '[email protected]',
  from: '[email protected]',
  template: 'bienvenida',
  data: { nombre: 'Ana', codigo: '12345' },
});

Bulk, grupos y programado

await mail.sendBulk({
  template: 'campana',
  from: '[email protected]',
  recipients: [{ email: '[email protected]', data: { nombre: 'Ana' } }],
});

await mail.sendToGroup({
  groupId: 'uuid-grupo',
  template: 'campana',
  data: { titulo: 'Novedades' },
});

await mail.send({
  to: '[email protected]',
  from: '[email protected]',
  template: 'recordatorio',
  scheduledAt: '2026-05-25T15:00:00.000Z',
  data: { nombre: 'Luis' },
});

API del SDK

| Método | Descripción | | ----------------------------------------- | ----------------------------- | | send(payload) | POST /api/emails/send | | sendTemplate(to, slug, data?, subject?) | Atajo con plantilla | | sendBulk(payload) | POST /api/emails/send/bulk | | sendBulkFromJson(payload) | Bulk desde JSON | | sendToGroup(payload) | POST /api/emails/send/group | | sendingIdentities.list() | Aliases listos para enviar | | sendingIdentities.get(id) | Detalle de identidad | | domains.list() / aliases.list() | Lectura con token API |

SendEmailPayload (campos principales)

| Campo | Tipo | Uso | | ----------------------------------------- | -------------------- | -------------------------------------------- | | to | string \| string[] | Destinatario(s) | | from | string? | Alias registrado (ej. [email protected]) | | aliasId | string? | UUID del alias (alternativa a from) | | domainId | string? | Forzar dominio si hay varios | | fromName | string? | Nombre visible del remitente | | subject, html, text | | Correo libre | | template, data | | Plantilla del dashboard | | scheduledAt | string? | ISO 8601 | | replyTo, cc, bcc, headers, tags | | Opcionales |

Guía completa

Paso a paso, cURL, Android, errores y recepción: SDK-GUIDE.md.