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

Domains

Domains are the foundation of every mailbox workspace.
This guide covers searching for domains, checking workspace conflicts, and managing forwarding.
INFO
Domain renewal operates independently from mailbox (subscription) renewal. See the Domain Renewal guide for the full renewal lifecycle.

Quick Reference#

AspectInformation
Route prefix/domains
Default auto-renewDisabled for all new domains
Payment methodPartner wallet balance
Async operationsForwarding, email forwarding, and client ID attachment are queue-based — a 200 response means accepted, not complete

Available Endpoints#

MethodEndpointDescription
POST/domains/availableCheck availability and pricing across multiple TLDs
POST/domains/available-singleCheck availability and pricing for a single domain
POST/domains/has-workspaceVerify no Google/Microsoft workspace exists for a domain
GET/domains/by-user?userId=List all domains owned by a user
POST/domains/add-forwardingSet URL forwarding on one or more domains
POST/domains/add-email-forwardingSet email catch-all forwarding on one or more domains
DELETE/domainsRemove domains (must have no mailboxes assigned)

Domain Status Reference#

StatusMeaning
ACTIVEDomain registered and operational
PENDINGRegistration in progress
GRACE_PERIODExpired — recoverable within 7 days
RENEWINGRenewal in progress (transient)
EXPIREDPast grace period — no longer recoverable
TRANSFERREDDomain transferred out
INACTIVEDeactivated

Domain Search & Pre-checks#

Check availability
Check for workspace conflicts
List user domains

Forwarding#

Domain forwarding
Email forwarding

Removing Domains#

DELETE /domains removes one or more domains. A domain must have no mailboxes assigned before it can be deleted. Returns 400 if any mailbox is still assigned.

Scenarios#

New Domain Registration#

1
Check availability
POST /domains/available — find available domains and prices.
2
Check workspace conflicts
POST /domains/has-workspace — confirm no existing workspace.
3
Place order
POST /orders/json?userId= — submit the order.
4
Confirm registration
Listen for domain.order.success or poll GET /domains/by-user?userId= until status = "ACTIVE".

Set Up Domain Forwarding#

1
Set forwarding
POST /domains/add-forwarding — submit the target URL.
2
Verify propagation
Poll GET /domains/by-user?userId= or test directly once DNS has propagated.

Remove a Domain#

1
Remove mailboxes
DELETE /mailboxes/remove — release every mailbox assigned to the domain.
2
Delete domain
DELETE /domains — pass the domain name in the request body.

Avoid These Common Issues#

Skipping the workspace check — Always call POST /domains/has-workspace before placing an order. A missed workspace conflict causes provisioning to fail after payment is taken.
Incorrect userId — Using the wrong user ID returns an empty domain list, not an error. Verify the value before querying.
Deferred forwarding — A 200 on forwarding endpoints means the job was queued, not that DNS has updated. Allow time for propagation before testing.
Deleting domains with mailboxes — Remove all mailboxes first. DELETE /domains returns 400 if any mailbox is still assigned.

Next Steps#

Domain Renewal
Renewal windows, grace periods, and eligibility rules.
DNS Management
Configure SPF, DKIM, DMARC, and nameservers.
Domain Events
Webhooks for registration and renewal outcomes.
Modified at 2026-08-05 16:12:50
Previous
Users
Next
DNS Management
Built with