Enterprise & Headless API

WazobiaMail provides a headless programmatic architecture designed for Enterprise customers who want to operate business email and inbox infrastructure entirely behind the scenes via code. Every operational capability available in the dashboard—domain provisioning, DNS inspection, mailbox creation, real-time event streaming, and direct mailbox inbox querying—can be driven programmatically via REST endpoints and WebSockets using your API keys.

Enterprise Plan Required: Enterprise headless features—including direct programmatic mailbox inbox retrieval (GET /mailboxes/{id}/messages), individual message inspection (GET /mailboxes/{id}/messages/{message_id}), message purging (DELETE /mailboxes/{id}/messages/{message_id}), and dedicated IP egress routing—strictly require an active Enterprise plan. Requests from accounts on Free, Starter, PAYG, or Business plans will receive an HTTP 403 Forbidden response.

1. Authentication & Headers

Authenticate API calls using the X-API-Key header or a Bearer token in the Authorization header. Enterprise API keys can be minted with full permissions (* or app:*) to perform all customer-facing operations.

X-API-Key: wzbm_live_your_enterprise_api_key

Alternatively:

Authorization: Bearer wzbm_live_your_enterprise_api_key
Content-Type: application/json

Keep your Enterprise API key secure in environment variables. Do not expose it in client-side code.

2. Domain Lifecycle & DNS Details

Headless domain setup allows your application to provision sending and receiving domains and immediately inspect the exact DNS records (SPF, DKIM, DMARC, MX) needed for verification.

Step 1: Register a domain

curl -X POST https://app.wazobiamail.com/api/v1/sending/domains \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "customer-domain.com",
    "useRootDomain": true,
    "hostInboxesOnMainDomain": true,
    "createDefaultInboxes": false
  }'

Step 2: Fetch DNS configuration records

Retrieve the generated DNS records required for mail exchange and cryptographic authenticity:

curl -X GET https://app.wazobiamail.com/api/v1/sending/domains/dom_abc12345/dns-records \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY"

The response includes the required TXT, MX, and CNAME records:

{
  "success": true,
  "message": "Sending domain DNS records fetched successfully",
  "data": {
    "domain": {
      "id": "dom_abc12345",
      "name": "customer-domain.com",
      "isVerified": false,
      "spfRecord": "v=spf1 include:relay.wazobiamail.com ~all",
      "dkimHost": "wazobiamail._domainkey.customer-domain.com",
      "dkimValue": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ...",
      "dmarcRecord": "v=DMARC1; p=quarantine; pct=100;",
      "mxRecords": [
        { "priority": 10, "host": "mx1.wazobiamail.com" },
        { "priority": 20, "host": "mx2.wazobiamail.com" }
      ]
    }
  }
}

Step 3: Trigger DNS verification

Once published to your DNS provider, trigger asynchronous DNS propagation verification:

curl -X POST https://app.wazobiamail.com/api/v1/sending/domains/dom_abc12345/verify \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

3. Mailbox Provisioning

Once your domain is verified, provision inboxes for team members, automated agents, or department routing.

Create a hosted mailbox

curl -X POST https://app.wazobiamail.com/api/v1/mailboxes \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "dom_abc12345",
    "localPart": "billing",
    "displayName": "Enterprise Billing Agent",
    "quotaMb": 5120
  }'

Inspect connection parameters

To obtain IMAP, SMTP, and POP3 connection endpoints for third-party client integrations:

curl -X GET https://app.wazobiamail.com/api/v1/mailboxes/box_xyz789/connection \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY"

4. Programmatic Mailbox Inbox API

Enterprise Plan Required: The Mailbox Messages endpoints require an active Enterprise plan. Accounts on lower plans will receive HTTP 403 Forbidden.

Enterprise applications can inspect, process, and purge inbound customer emails entirely over REST without running dedicated IMAP daemon workers.

List inbox messages

Fetch recent messages with pagination and unread filtering:

curl -X GET "https://app.wazobiamail.com/api/v1/mailboxes/box_xyz789/messages?page=1&limit=25&unreadOnly=false" \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY"

Example response:

{
  "success": true,
  "message": "Mailbox messages retrieved",
  "data": {
    "items": [
      {
        "id": "msg_01hxy9876",
        "threadId": "th_01hxy9876",
        "from": [
          { "name": "Sarah Connor", "email": "sconnor@cyberdyne.invalid" }
        ],
        "to": [
          { "name": "Enterprise Billing Agent", "email": "billing@customer-domain.com" }
        ],
        "subject": "Invoice #4028 Receipt Confirmation",
        "preview": "Thank you for sending over the updated receipt. Our accounts team has received...",
        "receivedAt": "2026-11-08T22:30:00Z",
        "isUnread": true,
        "hasAttachments": true,
        "sizeBytes": 28450
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 25
  }
}

Retrieve message detail

Fetch full message content, RFC 822 headers, HTML and plain text bodies, and attachment metadata:

curl -X GET "https://app.wazobiamail.com/api/v1/mailboxes/box_xyz789/messages/msg_01hxy9876" \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY"

Example response:

{
  "success": true,
  "message": "Mailbox message retrieved",
  "data": {
    "id": "msg_01hxy9876",
    "threadId": "th_01hxy9876",
    "from": [{ "name": "Sarah Connor", "email": "sconnor@cyberdyne.invalid" }],
    "to": [{ "name": "Enterprise Billing Agent", "email": "billing@customer-domain.com" }],
    "cc": [],
    "bcc": [],
    "replyTo": [],
    "subject": "Invoice #4028 Receipt Confirmation",
    "receivedAt": "2026-11-08T22:30:00Z",
    "isUnread": false,
    "htmlBody": "<p>Thank you for sending over the updated receipt.</p>",
    "textBody": "Thank you for sending over the updated receipt.",
    "attachments": [
      {
        "id": "att_01hxy",
        "name": "receipt_4028.pdf",
        "contentType": "application/pdf",
        "sizeBytes": 24500
      }
    ],
    "sizeBytes": 28450
  }
}

Delete an inbox message

Purge processed messages to manage mailbox quota:

curl -X DELETE "https://app.wazobiamail.com/api/v1/mailboxes/box_xyz789/messages/msg_01hxy9876" \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY"

5. Sending Outbound Messages

Send high-volume transactional or campaign emails through your enterprise dedicated egress pool:

curl -X POST https://app.wazobiamail.com/api/v1/sending/messages \
  -H "X-API-Key: YOUR_ENTERPRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "billing@customer-domain.com",
    "to": ["customer@example.com"],
    "subject": "Your Statement for November",
    "html": "<h1>Account Summary</h1><p>Your statement is ready for review.</p>",
    "text": "Account Summary\nYour statement is ready for review."
  }'

6. Real-Time Telemetry & WebSockets

Enterprise applications can subscribe to real-time events without polling. Connect to WazobiaMail’s Socket.IO gateways by passing your API key in the connection auth handshake:

import { io } from "socket.io-client";

const socket = io("https://app.wazobiamail.com/dns-setup", {
  auth: {
    token: process.env.WAZOBIA_ENTERPRISE_KEY
  },
  transports: ["websocket"]
});

socket.on("connect", () => {
  console.log("Connected to DNS setup real-time stream");
});

socket.on("dns:verified", (payload) => {
  console.log("Domain verified in real time:", payload);
});

socket.on("connect_error", (err) => {
  console.error("Connection failed:", err.message);
});

Complete Multi-Language Example

Below is a complete Node.js/TypeScript example automating domain inspection, mailbox creation, inbox checking, and outbound dispatch:

import fetch from "node-fetch";

const API_BASE = "https://app.wazobiamail.com/api/v1";
const API_KEY = process.env.WAZOBIA_ENTERPRISE_KEY;

if (!API_KEY) {
  throw new Error("Missing WAZOBIA_ENTERPRISE_KEY environment variable");
}

const headers = {
  "Content-Type": "application/json",
  "X-API-Key": API_KEY,
};

async function runEnterpriseWorkflow() {
  // 1. Add Domain
  const domRes = await fetch(`${API_BASE}/sending/domains`, {
    method: "POST",
    headers,
    body: JSON.stringify({ domain: "ops.enterprise.org", useRootDomain: true }),
  });
  const domData = await domRes.json();
  const domainId = domData.data?.id;
  console.log("Registered domain ID:", domainId);

  // 2. Fetch DNS Records
  const dnsPath = `${API_BASE}/sending/domains/{domain_id}/dns-records`.replace("{domain_id}", domainId);
  const dnsRes = await fetch(dnsPath, {
    headers,
  });
  const dnsData = await dnsRes.json();
  console.log("DKIM Record:", dnsData.data?.domain?.dkimValue);

  // 3. Create Mailbox
  const boxRes = await fetch(`${API_BASE}/mailboxes`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      domainId,
      localPart: "support",
      displayName: "Customer Operations",
    }),
  });
  const boxData = await boxRes.json();
  const mailboxId = boxData.data?.id;
  console.log("Created Mailbox ID:", mailboxId);

  // 4. Check Inbox (Enterprise Plan Required)
  const msgPath = `${API_BASE}/mailboxes/{id}/messages?limit=10`.replace("{id}", mailboxId);
  const msgRes = await fetch(msgPath, {
    headers,
  });
  if (msgRes.status === 403) {
    throw new Error("Enterprise plan required to access the Mailbox Inbox API");
  }
  const messages = await msgRes.json();
  console.log(`Found ${messages.data?.total || 0} messages`);
}

runEnterpriseWorkflow().catch(console.error);

Error Codes & Plan Enforcements

Status Code	Meaning	Resolution
`401 Unauthorized`	Invalid, missing, or expired API key	Verify your `X-API-Key` or `Authorization: Bearer` header.
`403 Forbidden`	Enterprise Plan Required	The requested operation requires an active Enterprise subscription tier. Upgrade your account or contact support.
`404 Not Found`	Resource does not exist or belongs to another tenant	Verify the mailbox ID, domain ID, or message ID.
`422 Unprocessable`	Validation failed	Review request body fields against constraints.

Start here

SDKs & libraries

Everyday email

Sending

Enterprise

Account

Enterprise & Headless API

Enterprise & Headless API

1. Authentication & Headers

2. Domain Lifecycle & DNS Details

Step 1: Register a domain

Step 2: Fetch DNS configuration records

Step 3: Trigger DNS verification

3. Mailbox Provisioning

Create a hosted mailbox

Inspect connection parameters

4. Programmatic Mailbox Inbox API

List inbox messages

Retrieve message detail

Delete an inbox message

5. Sending Outbound Messages

6. Real-Time Telemetry & WebSockets

Complete Multi-Language Example

Error Codes & Plan Enforcements

​Enterprise & Headless API

​1. Authentication & Headers

​2. Domain Lifecycle & DNS Details

​Step 1: Register a domain

​Step 2: Fetch DNS configuration records

​Step 3: Trigger DNS verification

​3. Mailbox Provisioning

​Create a hosted mailbox

​Inspect connection parameters

​4. Programmatic Mailbox Inbox API

​List inbox messages

​Retrieve message detail

​Delete an inbox message

​5. Sending Outbound Messages

​6. Real-Time Telemetry & WebSockets

​Complete Multi-Language Example

​Error Codes & Plan Enforcements

Enterprise & Headless API

1. Authentication & Headers

2. Domain Lifecycle & DNS Details

Step 1: Register a domain

Step 2: Fetch DNS configuration records

Step 3: Trigger DNS verification

3. Mailbox Provisioning

Create a hosted mailbox

Inspect connection parameters

4. Programmatic Mailbox Inbox API

List inbox messages

Retrieve message detail

Delete an inbox message

5. Sending Outbound Messages

6. Real-Time Telemetry & WebSockets

Complete Multi-Language Example

Error Codes & Plan Enforcements