> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazobiamail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise & Headless API

> Full programmatic lifecycle from domain provisioning and DNS verification to mailbox management, inbox retrieval, and transactional sending.

# 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.

> [!NOTE]
>
> **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.

```http theme={null}
X-API-Key: wzbm_live_your_enterprise_api_key
```

Alternatively:

```http theme={null}
Authorization: Bearer wzbm_live_your_enterprise_api_key
Content-Type: application/json
```

> [!TIP]
>
> 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

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

> [!NOTE]
>
> **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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.