Prewarmup Events

Pre-warmed mailboxes are different from standard mailbox provisioning:

Standard mailboxes → Created fresh, reputation builds from zero

Pre-warmed mailboxes → Already existed, warmed up, ready to send immediately with better deliverability

This makes them ideal for cold outreach campaigns where initial reputation matters.

When an order is placed via the Order Pre-Warmed-Up Mailboxes API, your system will receive real-time webhooks indicating whether the order was successful or failed.

⚙️ Sequence of Events

Order Creation

A successful API call returns an orderId and generates an invoice.

If the wallet balance is insufficient, the order fails, and a prewarmup.order.failed event is sent.

Payment Success

Once the invoice payment is successful, pre-warmed-up mailboxes are automatically assigned to the user.

Webhook Delivery

✅ On success → prewarmup.order.success

❌ On failure → prewarmup.order.failed

Important

A single order can include multiple domains. Each domain gets its own set of pre-warmed mailboxes. Some domains can succeed while others fail in the same order. You'll receive both prewarmup.order.success and prewarmup.order.failed for the same order if this happens.

All webhook events are sent as POST requests with a JSON body to your configured webhook URL.

prewarmup.order.success

This event is triggered when pre-warmed mailbox accounts are successfully assigned to the user from the available pool.

Example Payload

{
  "event": "prewarmup.order.success",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "orderId": "WR3N4JEW3D76N6KGRQSG36SSHBXK",
    "serviceProvider": "GOOGLE",
    "mailboxDetails": [
      {
        "domain": "example.com",
        "domainId": "LY25R9GK5AHYZ450YPWMNM8K8FXX",
        "domainExpiryDate": "2026-09-26T08:53:51.641Z",
        "domainCreatedAt": "2025-09-26T08:53:51.641Z",
        "subscriptionId": "KX9V77PVMFMZH4PTPF2Y99P2",
        "preWarmedUpMailboxes": [
          {
            "mailboxId": "LY25R9GK5AHYZ450YPWMNM8K8FXX",
            "email": "yasmeen.king@example.com",
            "firstName": "Yasmeen",
            "lastName": "King",
            "profilePicture": "https://cdn.zapmail.ai/mailboxes/James-Carter-SelectAll-1756754834597.jpg",
            "password": "$fFqf$PU7w$Lz9",
            "appPassword": "rena ppos micx xycp",
            "authenticatorSecret": "tukl dfds sloe oldf",
            "isAdmin": true,
            "warmingUpFrom": "2025-09-26T08:53:51.641Z",
            "expiryDate": "2025-11-27T19:59:17.294Z"
          },
          {
            "mailboxId": "FZHCRVTWEDMP2ZMMRSVZ63F493F1",
            "email": "mike.miller@example.com",
            "firstName": "Mike",
            "lastName": "Miller",
            "profilePicture": "https://cdn.zapmail.ai/mailboxes/James-Carter-SelectAll-1756754834597.jpg",
            "password": "$fFqf$PU7w$Lz9",
            "appPassword": "rena ppos micx xycp",
            "authenticatorSecret": "tukl dfds sloe oldf",
            "isAdmin": false,
            "warmingUpFrom": "2025-09-26T09:22:10.123Z",
            "expiryDate": "2025-11-27T19:59:17.294Z"
          }
        ]
      },
      {
        "domain": "example2.com",
        "domainId": "ERG9Y480R2M5H7PXCX9XS0K6VY0S",
        "domainExpiryDate": "2026-09-26T15:19:40.220Z",
        "domainCreatedAt": "2025-09-26T15:19:40.220Z",
        "subscriptionId": "EAG9Q69XN0MBS2GF13K2HEYRTQGS",
        "preWarmedUpMailboxes": [
          {
            "mailboxId": "ERG9Y480R2M5H7PXCX9XS0K6VY0S",
            "email": "yvonne.lesch@example2.com",
            "firstName": "Yvonne",
            "lastName": "Lesch",
            "profilePicture": "https://cdn.zapmail.ai/mailboxes/Olivia-Williams-default-1756417024026.jpg",
            "password": "$fFqf$PU7w$Lz9",
            "appPassword": "rena ppos micx xycp",
            "authenticatorSecret": "tukl dfds sloe oldf",
            "isAdmin": true,
            "warmingUpFrom": "2025-09-26T15:19:40.220Z",
            "expiryDate": "2025-11-27T19:59:17.294Z"
          }
        ]
      }
    ]
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"prewarmup.order.success"`
`eventId`	string	Unique identifier for this event
`data.userId`	string	User who placed the order
`data.userEmail`	string	User's email address
`data.orderId`	string	Unique order identifier
`data.serviceProvider`	string	`"GOOGLE"` or `"MICROSOFT"`
`data.mailboxDetails`	array	Array of domain allocations

Each item in mailboxDetails:

Field	Type	Description
`domain`	string	Domain name (e.g., `example.com`)
`domainId`	string	Unique identifier for this domain
`domainExpiryDate`	ISO 8601	When the domain registration expires (typically 1 year from creation)
`domainCreatedAt`	ISO 8601	When the domain was registered.
`subscriptionId`	string	Subscription ID for this domain — use this for renewal and subscription events
`preWarmedUpMailboxes`	array	Array of mailbox accounts assigned to this domain

Each mailbox in preWarmedUpMailboxes:

Field	Type	Description
`mailboxId`	string	Unique mailbox identifier
`email`	string	Full email address
`firstName`	string	First name
`lastName`	string	Last name
`profilePicture`	string	Profile picture URL
`password`	string	Account password
`appPassword`	string	App-specific password (for third-party integrations)
`authenticatorSecret`	string	2FA authenticator secret (for setting up 2FA)
`isAdmin`	boolean	Whether account has admin privileges
`warmingUpFrom`	ISO 8601	When the account started warming up
`expiryDate`	ISO 8601	When the subscription expires (renewal date)

prewarmup.order.failed

This event is triggered when pre-warmed mailbox assignment fails. This can happen at the order level or at the domain level.

Important: Partial failures

An order for multiple domains can have partial failures. For example:

domain-a.com → Success (accounts assigned)

domain-b.com → Failed (insufficient wallet)

In this case, you receive both prewarmup.order.success (for domain-a) and prewarmup.order.failed (for domain-b) for the same order.

Example Payload

{
  "event": "prewarmup.order.failed",
  "eventId": "KX6VYNA7W2M616JPFVT9JZX14B4N",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "orderId": "K57P9Y7T95M74ZPBRP9A415383AQ",
    "serviceProvider": "GOOGLE",
    "failedOrders": [
      {
        "domain": "yourcompanynow.info",
        "reason": "Pre-warmed mailboxes not available"
      },
      {
        "domain": "example2.com",
        "reason": "Insufficient wallet balance"
      }
    ]
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"prewarmup.order.failed"`
`eventId`	string	Unique identifier for this event
`data.userId`	string	User who placed the order
`data.userEmail`	string	User's email address
`data.orderId`	string	Order identifier
`data.serviceProvider`	string	`"GOOGLE"` or `"MICROSOFT"`
`data.failedOrders`	array	Array of failures

Each item in failedOrders:

Field	Type	Description
`domain`	string	Domain that failed
`reason`	string	Reason for failure

Common failure reasons

"Pre-warmed mailboxes not available" — Pool is empty for this domain/provider

"Insufficient wallet balance" — Not enough credits to cover cost

Important Notes

Expiry and Renewal

Pre-warmed mailboxes have the same subscription renewal flow as normal mailboxes

After expiryDate, the mailboxes will receive subscription.renewal.success or subscription.renewal.failed

Renewal uses the same subscription mechanism as normal mailboxes

Credentials Security

Store credentials encrypted in your database

Never log passwords or app passwords

Transmit credentials only over HTTPS to authenticated users

Consider implementing password rotation for users

Next Steps

Pre-Warmup

Order pre-warmed mailboxes that trigger these events.

Mailbox Events

What happens after domain registration succeeds.

Subscription Events

How mailbox subscription renewal works.

⚙️ Sequence of Events#

prewarmup.order.success#

Example Payload#

Payload Schema#

prewarmup.order.failed#

Important: Partial failures#

Example Payload#

Payload Schema#

Common failure reasons#

Important Notes#

Expiry and Renewal#

Credentials Security#

Next Steps#

⚙️ Sequence of Events

prewarmup.order.success

Example Payload

Payload Schema

prewarmup.order.failed

Important: Partial failures

Example Payload

Payload Schema

Common failure reasons

Important Notes

Expiry and Renewal

Credentials Security

Next Steps