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

Subscriptions

A Subscription is the billing record tied to a mailbox.
Every mailbox gets one automatically when provisioned. If a subscription lapses, the mailbox stops working.

How Subscriptions Work#

Subscriptions are created when a mailbox is ordered and renew automatically on a monthly or yearly cycle.
Renewal happens in one of two ways — automatically if autoRenew is enabled, or manually by calling POST /subscriptions/renew-subscriptions.
If a subscription is not renewed, it eventually moves to EXPIRED and the mailbox is disabled.

Subscription Statuses#

StatusMailbox works?Description
ACTIVE✅ YesSubscription is current
RENEWING✅ YesRenewal payment is processing
PAST_DUE⚠️ LimitedPayment failed
CANCELLED❌ NoExplicitly cancelled by partner
EXPIRED❌ NoSubscription not renewed — mailbox disabled

State Machine#

[ACTIVE] ──→ [RENEWING] ──→ [ACTIVE]       (payment succeeded)
                    ↓
              [PAST_DUE]                    (payment failed)
                    ├──→ [ACTIVE]           (renewed via API or auto-renew)
                    └──→ [EXPIRED]          (not renewed)

[ACTIVE] ──→ [CANCELLED]                   (partner cancelled)

Billing Cycles#

CyclePriceNotes
MONTHLY$3.00/mailbox/monthBilled monthly
INFO
Mailbox pricing starts at $3.00 per mailbox/month.
Subscriptions active for more than 12 months automatically renew at $5.00 per mailbox/month. Use POST /subscriptions/recreate to reset pricing without mailbox downtime. See 1+ Year Subscriptions.
Volume Discounts: Pricing can be negotiated for partners with high mailbox volumes. Contact the Support for custom pricing.

Available Endpoints#

MethodEndpointDescription
GET/subscriptions?userId=List subscriptions for a user
POST/subscriptions/renew-subscriptionsManually renew one or more subscriptions
POST/subscriptions/toggle-autorenewalEnable or disable auto-renewal per subscription
POST/subscriptions/cancelCancel one or more subscriptions immediately
POST/subscriptions/recreateRecreate subscriptions to reset pricing

Webhook Events#

EventFired when
subscription.renewingRenewal payment is being processed
subscription.renewal.successRenewal payment succeeded
subscription.renewal.failedRenewal payment failed → PAST_DUE
subscription.past_dueSubscription entered past-due state
subscription.cancelledCancelled by partner
subscription.expiredSubscription not renewed → EXPIRED
subscription.updatedSubscription record updated

Scenarios#

Recover from PAST_DUE#

1
Receive webhook
subscription.past_due fires — identify the affected subscriptions.
2
Update payment method
Customer updates their payment method via your UI and billing provider.
3
Renew
Call POST /subscriptions/renew-subscriptions with the affected subscriptionIds, or enable auto-renew via POST /subscriptions/toggle-autorenewal.
4
Confirm recovery
Listen for subscription.renewal.success — mailbox is restored.

Cancel a Subscription#

DANGER
POST /subscriptions/cancel is immediate and permanent. The mailbox moves to EXPIRED instantly with no prorated refunds.

Subscription Auto Renewal#

To stop future renewals without immediately expiring the mailbox, use POST /subscriptions/toggle-autorenewal instead.

Reset Long-Running Subscription Pricing#

1
Identify affected subscriptions
GET /subscriptions?userId= — find subscriptions approaching or past 12 months.
2
Recreate subscriptions
POST /subscriptions/recreate with subscriptionIds or domainNames. Pricing resets to $3/month with no mailbox downtime.

Avoid These Common Issues#

Not renewing after payment failure — When a payment fails, renew via POST /subscriptions/renew-subscriptions or ensure auto-renew is enabled. Subscriptions that are not renewed will expire.
Confusing cancel and expire — CANCELLED is a permanent partner action. EXPIRED means the subscription was not renewed — it can still be recovered. Treat these differently in your UI.
Using cancel to pause renewals — POST /subscriptions/cancel expires the mailbox instantly. Use toggle-autorenewal if you only want to stop future renewals.
Long-running pricing drift — After 12 months the price increases to $5/month. Use POST /subscriptions/recreate proactively to reset the cycle without downtime.

Next Steps#

1+ Year Subscriptions
How pricing changes after 12 months and how to reset to $3/month.
Subscription Events
Full webhook payloads for every subscription event.
Mailboxes
How mailbox status ties to subscription status.
Modified at 2026-08-05 16:12:50
Previous
Mailboxes
Next
Pre-Warmup
Built with