1. Core Concepts
  • Welcome to the Cold Mail Reseller API
  • Get Started
    • Overview
    • Authentication
    • Quick Start
  • Core Concepts
    • Users
    • Domains
    • DNS Management
    • Subscriptions
    • Pre-Warmup
    • Domain Renewal
    • Mailbox Warmup
    • OAuth Exports
    • Platform Exports
    • Mailboxes
    • Sandbox API
    • 1+ Year Subscriptions
  • API Reference
    • Users
      • List Users
      • Get User
      • Create User
      • Update User
      • Delete User
    • Geo
      • List Countries
      • List States
    • Domains
      • Domain Renewal
        • Get Domain Renewal Prices
        • Renew Domains
        • Toggle Domain Auto-Renew
      • Get Domain
      • List Available Aged Domains
      • Order Aged Domains
      • Get Domains by User
      • Check Domain Availability
      • Check Single Domain Availability
      • Check Workspace Existence
      • Set Domain Forwarding
      • Set Email Forwarding
      • Delete Domains
    • DNS
      • Get DNS Records
      • Add DNS Records
      • Update DNS Record
      • Update Nameservers
      • Delete DNS Record
    • Mailboxes
      • List Mailboxes
      • Get Mailboxes by User
      • Get Mailbox
      • Get Admin Mailbox Details
      • Update Mailbox Details
      • Delete Mailbox
    • Mailbox Warmup
      • Add Warmup to Mailbox
      • Toggle Warmup
      • Update Warmup Settings
      • Delete Warmup Subscription
    • Orders
      • Get Order Status
      • Get Order Details
      • Create Order
      • Create Order (JSON)
      • Create Mailbox Order (JSON)
      • Process Order
    • Subscriptions
      • 1+ Year Subscription
        • Recreate Subscription
      • Get Subscriptions
      • Renew Subscriptions
      • Cancel Subscription
      • Toggle Auto-Renewal
    • Exports
      • Platform Exports
        • Get Platform Credentials
        • Get Platform Workspaces
        • Add Platform Credential
        • Export Mailboxes to Platform
        • Update Platform Credential
        • Remove Platform Credential
      • OAuth Exports
        • Perform OAuth
        • Add Client ID to Domains
    • Pre-Warmup
      • Sandbox
        • Get Sandbox Pre-warmup Domains
        • Order Sandbox Pre-warmup
        • Reset Sandbox Pre-warmup
      • Get Pre-warmup Domains
      • Order Pre-warmup
    • Placement Test
      • Create Placement Order
      • Get Placement Reports
  • Resources
    • Errors
    • Rate Limits
    • Pagination
    • Sandbox
    • MCP
  • Webhooks
    • Overview
    • Events
      • DNS Events
      • Subscription Events
      • Prewarmup Events
      • Mailbox Warmup Events
      • Mailbox Events
      • Domain Events
  • Schemas
    • Error
    • Success
    • MessageResponse
    • User
    • Domain
    • ErrorResponse
    • Mailbox
    • Subscription
    • DnsRecord
    • Error Response
    • Pagination Meta
    • Action Error Response
    • PrewarmupOrderResult
    • OrderCreationResult
  1. Core Concepts

Mailboxes

A Mailbox is an email account (e.g. alice@mycoldoutreach.com) hosted on a CMR domain.
Mailboxes are the core resource used for cold email outreach. They are provisioned automatically as part of an order and can be managed through the CMR API.

Provisioning Flow#

Mailboxes are created automatically when an order completes.
They move through several provisioning stages before becoming available.
1
Order Accepted
The order is accepted and mailbox provisioning begins. Status: IN_PROGRESS
2
Creating Password
The mailbox account has been created with the email provider and the initial password is being configured. Status: CREATING_PASSWORD
3
Active
The mailbox is fully provisioned and ready for use. Status changes to ACTIVE, and the mailbox.created webhook is sent.
TIP
We recommend subscribing to the mailbox.created webhook instead of continuously polling the Mailboxes API.

Mailbox Statuses#

StatusDescription
IN_PROGRESSMailbox account is being created with the email provider.
CREATING_PASSWORDInitial password is being configured.
ACTIVEMailbox is fully provisioned and ready to send email.
EXPIREDSubscription has expired. Sending is disabled until renewed.

Warmup Statuses#

StatusDescription
PENDINGWarmup has been queued but hasn't started yet.
ACTIVEWarmup is currently running.
PAUSEDWarmup has been paused manually.
STOPPEDWarmup has finished or has been stopped.

Available Endpoints#

MethodEndpointDescription
GET/mailboxesList every mailbox across all users under your partner account. No userId param — response is nested as data.users[].mailboxes[], one entry per user.
GET/mailboxes/single?userId=List all mailboxes for one user (paginated; optional search, serviceProvider).
GET/mailboxes/mailbox?mailboxId=Retrieve a single mailbox by ID.
GET/mailboxes/admin-mailbox-details?userId=&mailboxId=Retrieve admin mailbox details.
PATCH/mailboxes/update-mailbox-details?userId=Update mailbox details or reset password.
DELETE/mailboxes/remove?userId=Permanently remove a mailbox.
WARNING
/mailboxes and /mailboxes/single are easy to confuse. Neither one fetches a single mailbox by ID — /mailboxes/single still returns a list (of one user's mailboxes), just narrower than the unscoped /mailboxes. For a single mailbox by ID, use /mailboxes/mailbox?mailboxId=.

Mailboxes List#

List Mailboxes (all users)
List Mailboxes (one user)
Single Mailbox
Admin Details
GET /mailboxes
Returns every mailbox across all users under your partner account, nested as data.users[].mailboxes[]. No userId param.
Supports pagination using:
page
limit
WARNING
Deleting a mailbox is permanent. Once removed, the email address cannot be recovered.

Common Workflows#

Provision a Mailbox#

1
Place an Order
Endpoint: POST /orders/json?userId=
Create a domain order with mailbox information.
2
Wait for Webhook
Listen for: mailbox.created

Add Mailboxes to an Existing Domain#

1
Create Mailbox Order
Endpoint: POST /orders/create-mailbox-order/json?userId=
Specify the existing domainId or existing subscriptionId
2
Receive Webhook
Each mailbox triggers a separate mailbox.created webhook.

Avoid These Common Issues#

Using a Mailbox Too Early: Wait until the mailbox status becomes ACTIVE before attempting to send email, export credentials, or connect it to an outreach platform.
Polling for Provisioning: Subscribe to the mailbox.created webhook instead of repeatedly polling the Mailboxes API for status updates.
Permanent Deletion: Removing a mailbox is irreversible. Ensure the mailbox is no longer needed before calling DELETE /mailboxes/remove.

Next Steps#

Mailbox Warmup
Learn how mailbox warmup improves sender reputation before launching campaigns.
Subscriptions
Understand mailbox billing, renewals, and subscription lifecycle.
Platform Exports
Export mailboxes to supported outreach platforms.
Modified at 2026-09-05 07:55:39
Previous
Platform Exports
Next
Sandbox API
Built with