1. Core Concepts
  • Welcome to the Cold Mail Reseller API
  • Get Started
    • Overview
    • Authentication
    • Quick Start
  • Core Concepts
    • Users
    • Domains
    • DNS Management
    • Mailboxes
    • Subscriptions
    • Pre-Warmup
    • Domain Renewal
    • 1+ Year Subscriptions
    • Mailbox Warmup
    • Platform Exports
    • OAuth Exports
    • Sandbox API
  • 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 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
      • Set Warmup Status
      • Disable Warmup
    • 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
        • Add Platform Credential
        • Export Mailboxes to Platform
        • 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
      • Domain Events
      • Mailbox Events
      • Subscription Events
      • Prewarmup Events
      • Mailbox Warmup 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/mailboxes?userId=List all mailboxes for a user.
GET/mailboxes/single?userId=&mailboxId=Retrieve a single mailbox.
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.

Mailboxes List#

List Mailboxes
Single Mailbox
Admin Details
GET /mailboxes?userId=
Returns all mailboxes belonging to a user.
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-08-05 16:12:50
Previous
DNS Management
Next
Subscriptions
Built with