API Reference

# Mailboxes

Create and manage individual sending mailboxes on your verified domains. Mailboxes are the `from` address used when sending email.

## Overview

| Method | Endpoint                               | Description                             |
| ------ | -------------------------------------- | --------------------------------------- |
| GET    | /api/mailboxes                         | List all mailboxes                      |
| POST   | /api/mailboxes                         | Create a mailbox                        |
| GET    | /api/mailboxes/:email                  | Get mailbox details (includes password) |
| PATCH  | /api/mailboxes/:email                  | Update a mailbox                        |
| DELETE | /api/mailboxes/:email                  | Delete a mailbox                        |
| GET    | /api/mailboxes/export                  | Export mailboxes as CSV                 |
| GET    | /api/mailboxes/export-list             | Export mailboxes as JSON                |
| GET    | /api/mailboxes/statistic               | Get mailbox count statistics            |
| POST   | /api/mailboxes/bulk-create             | Bulk create (async)                     |
| POST   | /api/mailboxes/bulk-delete             | Bulk delete (async)                     |
| POST   | /api/mailboxes/bulk-connect-instantly  | Connect to Instantly (async)            |
| POST   | /api/mailboxes/bulk-connect-smartlead  | Connect to Smartlead (async)            |
| POST   | /api/mailboxes/bulk-connect-emailbison | Connect to EmailBison (async)           |
| GET    | /api/mailboxes/:email/sep-connections  | Read a mailbox’s SEP connections        |

GET`/api/mailboxes`

## List Mailboxes

Returns a paginated list of all mailboxes. Filter by domain, project, warmup status, and more.

| Query param    | Type    | Default | Description                                                                   |
| -------------- | ------- | ------- | ----------------------------------------------------------------------------- |
| page           | integer | 1       | Page number                                                                   |
| limit          | integer | 30      | Items per page                                                                |
| email          | string  | —       | Filter by email address (partial match)                                       |
| search         | string  | —       | Free-text search across email and full name (partial match, case-insensitive) |
| domainName     | string  | —       | Filter by domain name                                                         |
| domainId       | string  | —       | Filter by domain UUID                                                         |
| projectId      | string  | —       | Filter by project UUID                                                        |
| projectName    | string  | —       | Filter by project name                                                        |
| isWarmupActive | boolean | —       | Filter by active warmup                                                       |
| createdFrom    | string  | —       | Created after date (ISO 8601)                                                 |
| createdTo      | string  | —       | Created before date (ISO 8601)                                                |

cURL

```bash
curl "https://api.v4.missioninbox.com/api/mailboxes?page=1&limit=30" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b"
```

Response

```json
{
  "data": [
    {
      "email": "sender@yourdomain.com",
      "fullName": "John Doe",
      "domainName": "yourdomain.com",
      "isWarmupActive": true,
      "warmedDays": 7,
      "totalWarmedDays": 7,
      "sent": 142,
      "projectId": null,
      "createdAt": "2026-02-20T10:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 30,
  "totalPages": 1
}
```

POST`/api/mailboxes`

## Create Mailbox

Creates a new mailbox on a verified domain. The domain portion of `email` must match a domain that is already verified.

| Field    | Type   | Required | Description                                                                                                                                                 |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| email    | string | Required | Full email address (e.g. sender@yourdomain.com)                                                                                                             |
| fullName | string | Required | Display name for the sender                                                                                                                                 |
| password | string | Optional | Mailbox password — cannot contain #                                                                                                                         |
| replyTo  | string | Optional | Forward replies to this address. Replies still land in the mailbox; outgoing mail carries no Reply-To header. 400 if the address is a Mission Inbox mailbox |

cURL

```bash
curl -X POST "https://api.v4.missioninbox.com/api/mailboxes" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "fullName": "John Doe",
    "password": "SecurePassword123!"
  }'
```

Response

```json
{
  "email": "sender@yourdomain.com",
  "fullName": "John Doe",
  "password": "StrongPassword123",
  "sent": 0,
  "warmedDays": 0,
  "totalWarmedDays": 0,
  "isWarmupActive": false,
  "domainId": "c6cffd67-1628-407e-bc92-e317ea852397",
  "domainName": "yourdomain.com",
  "createdAt": "2026-04-07T09:10:36.563Z",
  "updatedAt": "2026-04-07T09:10:36.563Z",
  "integrations": []
}
```

!

The `password` is returned in the creation response — this is the only time it is shown in full. Store it securely; it cannot be retrieved again. If you omit it, Mission Inbox auto-generates a password that is also returned in the response.

GET`/api/mailboxes/:email`

## Get Mailbox

Returns full details for a single mailbox including warmup state, send count, project and domain info. The response always includes the `password` field in plain text — use this endpoint to retrieve credentials for SMTP / IMAP connections.

cURL

```bash
curl "https://api.v4.missioninbox.com/api/mailboxes/sender@yourdomain.com" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b"
```

Response

```json
{
  "email": "john.doe@example.com",
  "fullName": "John Doe",
  "password": "SecurePassword123!",
  "sent": 142,
  "isWarmupActive": true,
  "warmupStartDate": "2026-02-06T10:00:00.000Z",
  "warmedDays": 14,
  "totalWarmedDays": 21,
  "domainId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "domainName": "example.com",
  "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "projectName": "Campaign Q1",
  "createdAt": "2026-02-20T10:00:00.000Z",
  "updatedAt": "2026-02-20T10:00:00.000Z"
}
```

PATCH`/api/mailboxes/:email`

## Update Mailbox

Updates one or more fields on an existing mailbox. Only the fields you include in the body are changed.

| Field      | Type    | Description                                                                                                                                                        |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| fullName   | string  | Display name for the sender                                                                                                                                        |
| password   | string  | New password — cannot contain #                                                                                                                                    |
| replyTo    | string  | Forward replies to this address; an empty string or null stops forwarding. Outgoing mail carries no Reply-To header. 400 if the address is a Mission Inbox mailbox |
| warmedDays | integer | Manually set the warmed days counter                                                                                                                               |

cURL

```bash
curl -X PATCH "https://api.v4.missioninbox.com/api/mailboxes/sender@yourdomain.com" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jane Doe"
  }'
```

DELETE`/api/mailboxes/:email`

## Delete Mailbox

Permanently deletes a mailbox. Returns `200 OK` on success.

cURL

```bash
curl -X DELETE "https://api.v4.missioninbox.com/api/mailboxes/sender@yourdomain.com" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b"
```

## Export

Export mailboxes with their credentials using the same filter parameters as the list endpoint. Both endpoints accept `projectId`, `domainId`, `domainName`, `isWarmupActive`, and date range filters.

| Endpoint                       | Format | Description                                                                                    |
| ------------------------------ | ------ | ---------------------------------------------------------------------------------------------- |
| GET /api/mailboxes/export      | CSV    | Downloads a .csv file — email, fullName, password, replyTo, sent, warmup data, domain, project |
| GET /api/mailboxes/export-list | JSON   | Returns a JSON array of the full mailbox objects including password                            |

CSV export

cURL

```bash
curl "https://api.v4.missioninbox.com/api/mailboxes/export?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b" \
  --output mailboxes.csv
```

JSON export

cURL

```bash
curl "https://api.v4.missioninbox.com/api/mailboxes/export-list?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b"
```

GET`/api/mailboxes/statistic`

## Mailbox Statistics

Returns a summary count of mailboxes broken down by readiness and warmup state.

| Field            | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| totalMailboxes   | Total number of mailboxes in your environment                  |
| readyForOutreach | Mailboxes that have completed warmup and are ready for sending |
| warmupRunning    | Mailboxes with an active warmup session                        |
| notUsed          | Mailboxes with no send activity                                |

cURL

```bash
curl "https://api.v4.missioninbox.com/api/mailboxes/statistic" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b"
```

Response

```json
{
  "totalMailboxes": 250,
  "readyForOutreach": 180,
  "warmupRunning": 50,
  "notUsed": 75
}
```

## SMTP & IMAP

Every mailbox can be accessed via standard SMTP (send) and IMAP (read) protocols. No separate endpoint is needed — use the mailbox credentials directly:

| Setting    | SMTP                   | IMAP                   |
| ---------- | ---------------------- | ---------------------- |
| Host       | cube1.missioninbox.com | cube1.missioninbox.com |
| Port       | 465                    | 993                    |
| Encryption | SSL/TLS                | SSL/TLS                |
| Username   | Mailbox email          | Mailbox email          |
| Password   | Mailbox password       | Mailbox password       |

The **cube host** is the entry point for all SMTP and IMAP traffic — shown in the sidebar under "SMTP / IMAP Host". The **username** is the full mailbox email address. Retrieve the **password** at any time via `GET /api/mailboxes/:email`.

JavaScript

```javascript
import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: 'cube1.missioninbox.com',
  port: 465,
  secure: true, // SSL/TLS
  auth: {
    user: 'sender@yourdomain.com',      // mailbox email
    pass: 'your_mailbox_password',       // set at creation or via PATCH
  },
});

await transporter.sendMail({
  from: 'sender@yourdomain.com',
  to:   'recipient@example.com',
  subject: 'Hello',
  text: 'Sent via Mission Inbox SMTP.',
});
```

See the [SMTP & IMAP Setup guide](https://doc.v4.missioninbox.com/sales/guides/smtp-imap.md) for full examples in JavaScript and Python, including IMAP usage.

## Bulk Operations

Bulk endpoints accept arrays and return a `taskId` immediately. Use the Tasks resource to monitor progress.

| Endpoint                        | Body                                                        |
| ------------------------------- | ----------------------------------------------------------- |
| POST /api/mailboxes/bulk-create | { mailboxes: \[{ email, fullName, password?, replyTo? }\] } |
| POST /api/mailboxes/bulk-delete | { emails: string\[\] }                                      |

All bulk responses: `{ "taskId": "uuid", "message": "..." }`

## SEP Integrations

Connect mailboxes to third-party Sales Engagement Platforms. All three endpoints accept an array of emails and return a `taskId` immediately. Use the Tasks resource to monitor progress.

| Endpoint                                    | Body                   |
| ------------------------------------------- | ---------------------- |
| POST /api/mailboxes/bulk-connect-instantly  | { emails: string\[\] } |
| POST /api/mailboxes/bulk-connect-smartlead  | { emails: string\[\] } |
| POST /api/mailboxes/bulk-connect-emailbison | { emails: string\[\] } |

All bulk responses: `{ "taskId": "uuid", "message": "..." }`

!

API keys for each platform must be configured in your Mission Inbox dashboard under **Settings → SEP Integration** before using these endpoints.

### Read a mailbox's SEP connections

`GET /api/mailboxes/:email/sep-connections` reports, per platform, when the mailbox was connected and the SMTP/IMAP endpoint a connect pushes (`expected`). Pass `provider` (`Instantly`, `SmartLead` or `Emailbison`) to report one platform only. `remoteStatus` says what the platform told us about the account: `ok`, `not_found`, `unsupported` or `error`.

None of the platforms report an account's SMTP/IMAP endpoint back, so `expected` is what we set, not a comparison. For Instantly it is authoritative right after a connect, because every connect rebuilds the account with these values.

cURL

```bash
curl "https://api.v4.missioninbox.com/api/mailboxes/sender@yourdomain.com/sep-connections?provider=Instantly" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b"
```

Response

```json
[
  {
    "provider": "Instantly",
    "connectedAt": "2026-09-01T10:00:00.000Z",
    "disconnectedAt": null,
    "externalId": null,
    "expected": {
      "smtpHost": "cube1.missioninbox.com",
      "smtpPort": 465,
      "smtpUsername": "sender@yourdomain.com",
      "imapHost": "cube1.missioninbox.com",
      "imapPort": 993,
      "imapUsername": "sender@yourdomain.com"
    },
    "endpointNote": "No SEP reports an account's SMTP/IMAP endpoint, so it cannot be read back for comparison.",
    "remoteDetails": { "email": "sender@yourdomain.com", "provider_code": 1 },
    "remoteStatus": "ok",
    "remoteMessage": null
  }
]
```

[PreviousDNS Provider Keys](https://doc.v4.missioninbox.com/sales/api/dns-credentials.md)[NextProjects](https://doc.v4.missioninbox.com/sales/api/projects.md)
