Integra correo en tu producto

Una integración, una organización

Cada API key pertenece a una aplicación y una organización cliente. El tenant se deriva de la credencial y no puede seleccionarse mediante datos de la solicitud.

• Owner crea aplicaciones, API keys y secretos de webhook
• Admin consulta actividad y reintenta entregas fallidas
• Los usuarios de buzón siguen autenticándose solo en Webmail

Ciclo completo de una integración

Crea una aplicación sandbox en Dashboard → Integraciones, emite una key con privilegios mínimos, llama a la API desde un servidor confiable, registra un webhook, completa su handshake de challenge y concilia las entregas con GET /v1/events. Para producción crea credenciales separadas; los secretos sandbox y production nunca son intercambiables.

• Los prefijos identifican keys sandbox (mdk_test_) o production (mdk_live_)
• La API key completa y el secreto whsec_ se revelan una sola vez cada uno
• Cada request, evento, entrega y replay permanece aislado por tenant y auditado

Comienza con el SDK TypeScript

Indica la URL de la API explícitamente hasta definir el dominio de producción. Guarda las keys en secretos del servidor y nunca las envíes al navegador.

                        import { MailDeck, MailDeckError } from '@maildeck/sdk';

const maildeck = new MailDeck({
  apiKey: process.env.MAILDECK_API_KEY!,
  baseUrl: process.env.MAILDECK_API_URL!,
});

const { items } = await maildeck.mailboxes.list();
                      

Superficie del SDK y transporte

Omnero Mail recibe baseUrl explícita, API key y una implementación fetch opcional. El SDK ofrece mailboxes.list, domains.list, messages.list/retrieve/send/update, events.list y métodos de endpoints, entregas y replay de webhooks. Las respuestas no 2xx lanzan MailDeckError con status, code estable y requestId.

                        try {
  const page = await maildeck.messages.list({ mailboxId, limit: 50 });
  await maildeck.messages.update(page.items[0].id, {
    mailboxId,
    isRead: true,
  });
} catch (error) {
  if (error instanceof MailDeckError) {
    console.error(error.status, error.code, error.requestId);
  }
}
                      

REST y eventos conservan el mismo estado

Usa REST para comandos y conciliación. Usa webhooks firmados para notificación inmediata. Ambas superficies señalan los mismos mensajes y estados canónicos.

• Contrato OpenAPI 3.1 en /openapi.yaml
• Listados por cursor en /v1/messages y /v1/events
• Webhooks al menos una vez con deduplicación por event ID

Ruta canónica de procesamiento

POST /v1/messages valida ownership y capacidad del plan, reserva la clave de idempotencia, escribe un job outbound y responde 202. Los workers construyen MIME, persisten el objeto enviado, lo entregan a SES y publican eventos canónicos. Los webhooks notifican; GET /v1/messages y GET /v1/events permiten conciliar después de una caída.

Mapa de recursos y endpoints

La superficie v1 expone descubrimiento de buzones y dominios, mensajes paginados por cursor, mutaciones de estado, carga y descarga de adjuntos, eventos canónicos, endpoints webhook, inspección de entregas y replay. Consulta OpenAPI 3.1 para schemas, status codes y el envelope estable de error.

• GET /v1/mailboxes y /v1/domains descubren recursos del tenant
• GET/POST /v1/messages y GET/PATCH /v1/messages/{messageId} operan correo
• POST /v1/attachments y GET /v1/attachments/{attachmentId}/download transfieren adjuntos
• GET /v1/events recupera el historial después de una caída
• GET/POST /v1/webhook-endpoints y listado/replay operan webhooks