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

Sandbox API

The sandbox environment lets you build and test your integration without touching real domains, mailboxes, or billing. Every endpoint mirrors production — same request shapes, same response shapes, same webhook payloads — but all data is isolated, no DNS is touched, and no money moves.

Quick Reference#

AspectInformation
Route prefix/sandbox
Base URLhttps://api.coldmailreseller.com/api/v1/sandbox
Auth headercmr-x-sandbox-api-key (separate from your production cmr-api-key)
Scenario headercmr-x-sandbox-scenario (optional — defaults to the happy path)
Webhook destinationsConfigured separately from production, under Test Mode

Authentication#

Getting your sandbox API key#

Log in to the partner dashboard → Settings → Integrations → switch to Test Mode. Your sandbox API key is shown there.

Required header#

Every sandbox request must include:
This is separate from your production API key (cmr-api-key). Using the wrong key returns 401 Unauthorized.

Base URL#

https://api.coldmailreseller.com/api/v1/sandbox

Webhook Destinations#

Sandbox webhook destinations are separate from your production webhooks — events from sandbox API calls only go to destinations registered here, never to your production receivers.
The easiest way to register a destination is the partner dashboard: Settings → Webhooks → Test Mode → add your URL there, no API call needed.
Once registered, all sandbox webhook events are delivered to it.

Available Endpoints#

Users#

MethodEndpointScenario
POST/sandbox/usersCreate user
GET/sandbox/users/listList users
GET/sandbox/users?userId=Get user
PUT/sandbox/users?userId=Update user
DELETE/sandbox/users?userId=Delete user

Domains#

MethodEndpointScenario
POST/sandbox/domains/availableSuggest domains — simulate:domain-unavailable
POST/sandbox/domains/available-singleCheck one domain — simulate:domain-unavailable
GET/sandbox/domains/by-user?userId=List domains
DELETE/sandbox/domains?userId=Delete domains
POST/sandbox/domains/has-workspaceWorkspace check — simulate:workspace-exists

DNS Records#

MethodEndpointScenario
GET/sandbox/domains/dns?userId=&domain=Get records
POST/sandbox/domains/dns?userId=&domain=Add record
PUT/sandbox/domains/dns?userId=Update record
DELETE/sandbox/domains/dns?userId=Delete record

Orders#

MethodEndpointScenario
POST/sandbox/orders/json?userId=Domain + mailbox order — simulate:order-success, simulate:order-domain-failed, simulate:order-mailbox-failed, simulate:order-partial-failure
POST/sandbox/orders/create-mailbox-order?userId=Mailbox-only order
GET/sandbox/orders?userId=&orderId=Get order details
GET/sandbox/orders/status?userId=&orderId=Get order status
POST/sandbox/orders/process-order?userId=Process queued order

Mailboxes#

MethodEndpointScenario
GET/sandbox/mailboxes?userId=List mailboxes
GET/sandbox/mailboxes/single?userId=&mailboxId=Get mailbox
GET/sandbox/mailboxes/mailbox?userId=&domain=Get by domain
POST/sandbox/mailboxes/validate-mailbox?userId=Validate
POST/sandbox/mailboxes/oauth?userId=OAuth stub
PATCH/sandbox/mailboxes/update-mailbox-details?userId=Update details
GET/sandbox/mailboxes/admin-mailbox-details?userId=Admin details
DELETE/sandbox/mailboxes/remove?userId=Remove mailbox — simulate:mailbox-export-failed

Subscriptions#

MethodEndpointScenario
GET/sandbox/subscriptions?userId=List subscriptions
POST/sandbox/subscriptions/renew?userId=Renew — simulate:subscription-renewal-failed, simulate:subscription-past-due
POST/sandbox/subscriptions/cancel?userId=Cancel
POST/sandbox/subscriptions/toggle-autorenewal?userId=Toggle auto-renewal

Pre-Warmup#

MethodEndpointScenario
GET/sandbox/pre-warmup?userId=List domains
POST/sandbox/pre-warmup/order?userId=Place order — simulate:prewarmup-order-failed
DELETE/sandbox/pre-warmup/reset?userId=Reset state

Geo#

MethodEndpointScenario
GET/sandbox/geo/countriesList countries
GET/sandbox/geo/countries/:countryCode/statesList states

Webhooks#

MethodEndpointScenario
POST/sandbox/webhooks/:eventId/replayReplay a past event

Scenario Simulation#

Attach this header to any request to force a specific outcome:
If absent or unrecognized, the default happy-path runs.
Scenario keyApplies toWhat it does
simulate:order-successPOST /orders/json(default) Full happy path — domains registered, mailboxes created, subscription active
simulate:order-domain-failedPOST /orders/jsonAll domains fail — no rows created, domain.order.failed webhook fired
simulate:order-mailbox-failedPOST /orders/jsonDomains created, mailbox provisioning fails — mailbox.order.failed webhook fired
simulate:order-partial-failurePOST /orders/jsonFirst domain succeeds, the rest fail — cart ends as PAID, no failure webhook
simulate:domain-unavailablePOST /domains/available, POST /domains/available-singleReturns 0 results
simulate:workspace-existsPOST /domains/has-workspaceReturns 409 (single) or success: false (bulk)
simulate:subscription-renewal-successPOST /subscriptions/renew(default) Renewal succeeds
simulate:subscription-renewal-failedPOST /subscriptions/renewRenewal fails — subscription.renewal.failed webhook fired
simulate:subscription-past-duePOST /subscriptions/renewSets PAST_DUE — subscription.past_due webhook fired
simulate:mailbox-export-successDELETE /mailboxes/remove(default) Export completes immediately
simulate:mailbox-export-failedDELETE /mailboxes/removeExport fails — mailbox.export.failed webhook fired
simulate:prewarmup-order-successPOST /pre-warmup/order(default) Pre-warmup order succeeds
simulate:prewarmup-order-failedPOST /pre-warmup/orderNo inventory — prewarmup.order.failed webhook fired

Avoid These Common Issues#

Using your production key in sandbox: cmr-x-sandbox-api-key is a distinct key from cmr-api-key. Sending your production key to a sandbox endpoint returns 401 Unauthorized.
Expecting sandbox events on your production webhook URL: Sandbox and production webhook destinations are registered separately under Test Mode. Events from sandbox calls never reach your production receivers, and vice versa.
Forgetting the scenario header defaults to the happy path: If cmr-x-sandbox-scenario is omitted or unrecognized, the request behaves as simulate:*-success — you won't see failure behavior unless you explicitly request it.
Assuming sandbox data carries over to production: Sandbox users, domains, and mailboxes are fully isolated. Nothing you create in sandbox appears in production, and there's no migration path between them.
Not resetting pre-warmup state between test runs: Stale sandbox pre-warmup data can interfere with subsequent tests. Call DELETE /sandbox/pre-warmup/reset?userId= between runs.

Next Steps#

Quick Start
Provision your first domain and mailbox, with a sandbox testing walkthrough.
Pre-Warmup
Order pre-warmed mailboxes — also covers sandbox testing for this flow.
Errors
HTTP status codes and retry strategy that apply in sandbox too.
Modified at 2026-08-05 16:12:50
Previous
OAuth Exports
Next
List Users
Built with