SDK de MailMask

Cliente oficial TypeScript/JavaScript para la API de MailMask. Crea aliases, gestiona dominios, envía emails y más desde tu código.

npm: @easybits.cloud/mailmask

Instalación

npm install @easybits.cloud/mailmask

Autenticación

Para usar el SDK necesitas una API Key. Puedes crear una desde el Dashboard en la sección de API Keys. Requiere plan Developer o Agencia.

Las API keys tienen el prefijo mk_ y solo se muestran una vez al crearlas. Guárdala en un lugar seguro.

import { MailMask } from "@easybits.cloud/mailmask";

const mm = new MailMask({ apiKey: "mk_..." });

Dominios

Gestiona los dominios conectados a tu cuenta. Puedes listar, agregar, verificar y consultar el estado de salud DNS.

// Listar dominios
const domains = await mm.domains.list();

// Obtener un dominio
const domain = await mm.domains.get("domain-id");

// Agregar dominio
const { domain } = await mm.domains.create("example.com");

// Eliminar dominio
await mm.domains.delete("domain-id");

// Verificar DNS
await mm.domains.verify("domain-id");

// Estado de salud
const health = await mm.domains.health("domain-id");

Aliases

Crea y administra aliases de email. Cada alias reenvía correo a uno o múltiples destinos.

// Listar aliases
const aliases = await mm.aliases.list("domain-id");

// Crear alias
const alias = await mm.aliases.create("domain-id", {
  alias: "hello",
  destinations: ["me@gmail.com"]
});

// Crear alias con múltiples destinos
const alias = await mm.aliases.create("domain-id", {
  alias: "team",
  destinations: ["alice@company.com", "bob@company.com"]
});

// Actualizar alias
await mm.aliases.update("domain-id", "hello", { enabled: false });

// Eliminar alias
await mm.aliases.delete("domain-id", "hello");

Reglas

Las reglas permiten enrutar o filtrar emails automáticamente según criterios como remitente, asunto o contenido.

// Listar reglas
const rules = await mm.rules.list("domain-id");

// Crear regla
const rule = await mm.rules.create("domain-id", {
  field: "from",
  match: "contains",
  value: "@newsletter.com",
  action: "forward",
  target: "newsletters@gmail.com"
});

// Actualizar regla
await mm.rules.update("domain-id", "rule-id", { enabled: false });

// Eliminar regla
await mm.rules.delete("domain-id", "rule-id");

Envío de emails

Envía emails individuales o masivos desde cualquier alias de tu dominio.

// Enviar email
await mm.send.send("domain-id", {
  from: "hello",
  fromName: "Mi Tienda",
  to: "client@example.com",
  subject: "Hola!",
  html: "<p>Contenido del email</p>"
});

// Envío masivo
const job = await mm.send.bulkSend("domain-id", {
  from: "hello",
  recipients: ["a@test.com", "b@test.com"],
  subject: "Newsletter",
  html: "<p>Contenido</p>"
});

// Consultar estado del envío masivo
const status = await mm.send.bulkStatus("domain-id", job.jobId);

Logs

Consulta el historial de emails procesados por un dominio.

const logs = await mm.logs.list("domain-id");

Credenciales SMTP

Crea credenciales SMTP para enviar emails desde tu código o aplicaciones SaaS. Disponible solo en plan Developer.

// Listar credenciales
const creds = await mm.smtp.list("domain-id");

// Crear credencial
const cred = await mm.smtp.create("domain-id", "Mi app");
console.log(cred.smtpPassword); // Solo se muestra una vez

// Revocar credencial
await mm.smtp.revoke("domain-id", "cred-id");

API Keys

Administra tus API keys programáticamente. Útil para rotación automática de credenciales.

// Listar keys
const keys = await mm.apiKeys.list();

// Crear key
const newKey = await mm.apiKeys.create("Mi nueva key");
console.log(newKey.key); // mk_... — solo se muestra una vez

// Revocar key
await mm.apiKeys.revoke("key-id");

Manejo de errores

El SDK lanza MailMaskError para respuestas HTTP no exitosas. Incluye el código de estado y el mensaje del servidor.

import { MailMask, MailMaskError } from "@easybits.cloud/mailmask";

try {
  await mm.domains.create("example.com");
} catch (err) {
  if (err instanceof MailMaskError) {
    console.error(err.status, err.message);
  }
}

MCP Server

// claude_desktop_config.json (próximamente)
{
  "mcpServers": {
    "mailmask": {
      "command": "npx",
      "args": ["@easybits.cloud/mailmask-mcp"],
      "env": { "MAILMASK_API_KEY": "mk_..." }
    }
  }
}

Referencia API

Para la referencia completa de la API HTTP (todos los endpoints, parámetros y respuestas), consulta la documentación interactiva: