Build email into your product

One integration, one tenant

Every API key belongs to one developer application and one customer organization. The tenant comes from the credential and cannot be selected through request data.

• Owner creates applications, API keys, and webhook secrets
• Admin can inspect activity and retry delivery failures
• Mailbox users continue to authenticate only in Webmail

End-to-end integration lifecycle

Create a sandbox application in Dashboard → Integrations, issue a least-privilege key, call the API from a trusted server, register a webhook, complete its challenge handshake, and reconcile deliveries with GET /v1/events. Promote by creating separate production credentials; sandbox and production secrets are never interchangeable.

• API key prefixes identify sandbox (mdk_test_) or production (mdk_live_) credentials
• The complete API key and whsec_ webhook secret are each revealed only once
• Every request, event, delivery, and replay remains tenant-scoped and auditable

Start with the TypeScript SDK

Pass the API URL explicitly until the production domain is selected. Store API keys in server-side secret storage and never ship them to a browser.

                        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();
                      

SDK surface and transport behavior

Omnero Mail accepts an explicit baseUrl, API key, and optional fetch implementation. The SDK provides mailboxes.list, domains.list, messages.list/retrieve/send/update, events.list, and webhook endpoint, delivery, and replay methods. Non-2xx responses throw MailDeckError with status, stable code, and 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 and event surfaces stay consistent

Use REST for commands and reconciliation. Use signed webhooks for low-latency notification. Both surfaces refer to the same canonical messages and delivery states.

• OpenAPI 3.1 contract at /openapi.yaml
• Cursor-based lists at /v1/messages and /v1/events
• At-least-once webhooks with event ID deduplication

Canonical processing path

POST /v1/messages validates ownership and plan capacity, reserves the idempotency key, writes an outbound job, and returns 202. Workers build MIME, persist the sent object, submit through SES, and publish canonical events. Webhooks notify; GET /v1/messages and GET /v1/events provide reconciliation when a consumer was offline.

Resource and endpoint map

The v1 surface exposes mailbox and domain discovery, cursor-paginated messages, message state mutations, attachment upload/download, canonical events, webhook endpoints, delivery inspection, and replay. Consult the OpenAPI 3.1 document for request schemas, status codes, and the stable error envelope.

• GET /v1/mailboxes and /v1/domains discover tenant-owned resources
• GET/POST /v1/messages and GET/PATCH /v1/messages/{messageId} operate mail
• POST /v1/attachments and GET /v1/attachments/{attachmentId}/download transfer attachments
• GET /v1/events restores event history after downtime
• GET/POST /v1/webhook-endpoints plus delivery list/replay operate webhooks