Create Mailbox Order (JSON)

This endpoint allows you to create mailbox orders for your domain. The behavior varies depending on your subscription status and confirmation parameter.

Request Scenarios

🟢 Scenario 1: Active Subscription

When you already have an active subscription, this endpoint adds new mailboxes to the existing subscription.

Required Parameter

subscriptionId

Use Cases

Adding additional mailboxes to your current plan

Scaling mailbox capacity within an existing subscription

🟠 Scenario 2: Cancelled Subscription

When your subscription has been cancelled, this endpoint creates mailboxes and automatically generates a new subscription.

Required Parameters

domainId

autoRenew

serviceProvider

Use Cases

Creating a new subscription for an existing domain whose previous subscription was cancelled

Order Processing

✅ Confirmed Orders (`confirm: true`)

When confirm is set to true:

Order will be created and automatically queued for processing

Your wallet must have sufficient balance to cover the order cost

Processing begins immediately after creation

⏸️ Unconfirmed Orders (`confirm: false`)

When confirm is set to false:

Order will be created but not processed

To process the order later, use the Process Order endpoint

Useful for reviewing order details before committing

Important Notes

Mutually Exclusive Parameters

Provide either subscriptionId or domainId

Do not provide both in the same request

Wallet Balance Requirement

Ensure sufficient balance in your wallet when using confirm: true

Insufficient balance will result in order creation failure

Automatic Subscription Creation

A new subscription is created automatically when using domainId

When creating a new subscription (Scenario 2), the autoRenew parameter to specify renewal preferences

Subscription Continuity

When using subscriptionId, mailboxes are added seamlessly to the existing plan

Summary

Parameter	Type	Required	Description
subscriptionId	string	Conditional*	ID of the active subscription to add mailboxes to
domainId	string	Conditional*	ID of the domain used to create a new subscription
autoRenew	boolean	Conditional**	Auto-renewal setting for new subscriptions (Scenario 2 only)
confirm	boolean	Required	`true`: Process immediately, `false`: Create without processing

* One of subscriptionId or domainId must be provided based on your subscription status
** Required only when using domainId (Scenario 2) to create a new subscription

Email Warmup (`onWarmup`)

Optionally enable warmup when creating mailboxes by setting onWarmup: true on individual mailbox objects.

{
  "mailboxes": {
    "example.org": [
      { "username": "alice", "firstName": "Alice", "lastName": "Smith", "onWarmup": true },
      { "username": "bob", "firstName": "Bob", "lastName": "Jones", "onWarmup": false }
    ]
  }
}

Field	Type	Required	Description
`onWarmup`	boolean	No	If `true`, enrolls the mailbox in email warmup after provisioning. Defaults to `false`.

Notes

Enrollment runs automatically — no extra API call is required after the order completes

To add warmup later to an already-active mailbox, use POST /mailboxes/{mailboxId}/warmup

curl --location 'https://customers.coldmailreseller.com/api/v1/integration/orders/create-mailbox-order/json?userId=H8M9JV2S9HMPYFQW393AZHQVD4XM' \ --header 'cmr-x-api-key: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "mailboxes": { "property1": [ { "username": "bob", "firstName": "Bob", "lastName": "Smith", "onWarmup": true } ], "property2": [ { "username": "bob", "firstName": "Bob", "lastName": "Smith", "onWarmup": true } ] }, "subscriptionId": "sub_V2M9KP3XAQZL", "domainId": "dom_V2M9KP3XAQZL", "serviceProvider": "GOOGLE", "domains": [ { "domain": "acmecorp.com", "years": 1 } ], "autoRenew": true, "confirm": true, "google": { "googleOauthRoute": "string", "clientId": "string", "appName": "string" }, "microsoftOauthRoute": "https://yourapp.com/oauth/microsoft/callback", "billingCycle": "MONTHLY" }'

{ "status": 200, "message": "Order created and queued for processing, make sure to have enough balance in your wallet!", "data": { "orderId": "ord_R8K2LQPZA9XM", "unavailableDomains": [ "string" ] }, "actionId": "ACT_7a078272-0fa7-4db4-a85b-c78697dacea1" }

Request Scenarios#

🟢 Scenario 1: Active Subscription#

🟠 Scenario 2: Cancelled Subscription#

Order Processing#

✅ Confirmed Orders (confirm: true)#

⏸️ Unconfirmed Orders (confirm: false)#

Important Notes#

Summary#

Email Warmup (onWarmup)#

Notes#

Request

Responses