Mailbox Events

Mailbox events are triggered when mailbox accounts are ordered, created, or modified.

Overview

The mailbox event lifecycle has three stages:

Order processing — Mailbox provisioning order is submitted to provider (Google/Microsoft)

Individual creation — Each mailbox account is created and activated

Updates — User modifies mailbox details (first name, profile picture, etc.)

mailbox.order.success

This event is triggered when the mailbox provisioning order is successfully submitted to the provider and confirmed. The mailboxes are now being created.

When it occurs

Domain registration succeeded (see domain.order.success)

Mailbox order is submitted to Google Workspace or Microsoft 365

Provider confirms the order is processing

Individual mailbox accounts are about to be created

Example Payload

{
  "event": "mailbox.order.success",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
    "domainName": "company.com",
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "subscriptionId": "YC2H6C87PPKPG5WXVNQ682GAVFTM",
    "orderId": "NQ682GAVFTMYC2H6C87PPKPG5WXV",
    "workspaceType": "GOOGLE",
    "creationtime": "2024-03-08T23:59:59Z",
    "expiryDate": "2025-03-08T23:59:59Z",
    "price": 11,
    "quantity": 3
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"mailbox.order.success"`
`eventId`	string	Unique identifier for this event
`data.domainId`	string	The domain these mailboxes belong to
`data.domainName`	string	Domain name (e.g., `company.com`)
`data.userId`	string	User who placed the order
`data.userEmail`	string	User's email address
`data.subscriptionId`	string	Important: Unique subscription ID for this domain
`data.orderId`	string	Order identifier
`data.workspaceType`	string	`"GOOGLE"` or `"MICROSOFT"`
`data.creationtime`	ISO 8601	When the order was placed
`data.expiryDate`	ISO 8601	When the subscription expires (renewal date)
`data.price`	number	Price per mailbox
`data.quantity`	number	Number of mailboxes in this order

mailbox.order.failed

This event is triggered when the mailbox provisioning order fails. This usually means individual mailbox accounts were not created.

When it occurs

Domain was successfully registered, but mailbox order failed

Provider rejects the mailbox request (billing, quota, domain issues)

Insufficient mailbox quota in the workspace

Domain verification is incomplete

Payment processing failed

Example Payload

{
  "event": "mailbox.order.failed",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "subscriptionId": "YC2H6C87PPKPG5WXVNQ682GAVFTM",
    "orderId": "NQ682GAVFTMYC2H6C87PPKPG5WXV",
    "domain": "company.com",
    "mailboxDetails": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john"
    },
    "workspaceType": "GOOGLE",
    "price": 11,
    "quantity": 2,
    "reason": "Domain not verified"
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"mailbox.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.subscriptionId`	string	Subscription ID (for reference)
`data.domain`	string	Domain name
`data.workspaceType`	string	`"GOOGLE"` or `"MICROSOFT"`
`data.mailboxDetails`	object	Sample mailbox details from the order
`data.mailboxDetails.firstName`	string	First name provided
`data.mailboxDetails.lastName`	string	Last name provided
`data.mailboxDetails.email`	string	Email username provided
`data.price`	number	Price per mailbox
`data.quantity`	number	Number of mailboxes attempted
`data.reason`	string	Reason for failure

mailbox.created

This event is triggered when an individual mailbox account is successfully created and ready to use. This event is sent once per mailbox.

When it occurs

Mailbox provisioning order succeeded

Individual mailbox account was created at the provider

Account is verified and ready to use

Credentials are available and secure

Example Payload (Google)

{
  "event": "mailbox.created",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "domain": "coldmailseller.com",
    "subscriptionId": "PMHKDLSOTJSNLGOOSFD",
    "orderId": "WR3N4JEW3D76N6KGRQSG36SSHBXK",
    "workspaceType": "GOOGLE",
    "mailboxDetails": {
      "mailboxId": "LY25R9GK5AHYZ450YPWMNM8K8FXX",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@coldmailseller.com",
      "password": "TempPass123!",
      "appPassword": "rena ppos micx xycp",
      "secret":"toqm iemx qeuc ud6f 3lke ds7f mcju 5i7s",
      "isAdmin": true,
      "creationTime": "2024-03-08T23:59:59Z",
      "expiryDate": "2025-03-08T23:59:59Z"
    },
    "price": 8.16
  }
}

Example Payload (Microsoft)

{
  "event": "mailbox.created",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "domain": "coldmailseller.com",
    "subscriptionId": "PMHKDLSOTJSNLGOOSFD",
    "orderId": "WR3N4JEW3D76N6KGRQSG36SSHBXK",
    "workspaceType": "MICROSOFT",
    "finalUrl": "https://example.com/oauth-callback",
    "mailboxDetails": {
      "mailboxId": "LY25R9GK5AHYZ450YPWMNM8K8FXX",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@coldmailseller.com",
      "password": "TempPass123!",
      "secret":"toqm iemx qeuc ud6f 3lke ds7f mcju 5i7s",
      "creationTime": "2024-03-08T23:59:59Z",
      "expiryDate": "2025-03-08T23:59:59Z"
    },
    "price": 11
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"mailbox.created"`
`eventId`	string	Unique identifier for this event
`data.userId`	string	User who owns the mailbox
`data.userEmail`	string	User's email address
`data.domain`	string	Domain the mailbox belongs to
`data.subscriptionId`	string	Subscription ID (groups mailboxes by domain)
`data.orderId`	string	Order this mailbox belongs to
`data.workspaceType`	string	`"GOOGLE"` or `"MICROSOFT"`
`data.mailboxDetails.mailboxId`	string	Unique mailbox identifier
`data.mailboxDetails.firstName`	string	First name
`data.mailboxDetails.lastName`	string	Last name
`data.mailboxDetails.email`	string	Full email address
`data.mailboxDetails.appPassword`	string	(Google only) App-specific password
`data.mailboxDetails.password`	string	Account password
`data.mailboxDetails.secret`	string	Account secret
`data.mailboxDetails.isAdmin`	boolean	Whether account has admin privileges
`data.mailboxDetails.creationTime`	ISO 8601	When account was created
`data.mailboxDetails.expiryDate`	ISO 8601	When subscription expires
`data.price`	number	Price of this mailbox

mailbox.updated

This event is triggered when a user updates mailbox details such as first name, last name, username, or profile picture.

When it occurs

User modifies their profile information

User uploads a new profile picture

Admin updates mailbox details

System syncs profile changes

Example Payload

{
  "event": "mailbox.updated",
  "eventId": "Q9F81GPR7S4QWQG17D89TV3FN4E4",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "userEmail": "johndoe@company.com",
    "mailboxId": "3JP15CC4YWMHYFNYFCPM9A486E1R",
    "domain": "demo.biz",
    "email": "alice.y@demo.biz",
    "workspaceType": "GOOGLE",
    "updatedFields": {
      "firstName": "Alice",
      "lastName": "White",
      "userName": "ali",
      "profilePicture": "https://images.unsplash.com/photo-1742147550712-9c25dc0832aa"
    }
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"mailbox.updated"`
`eventId`	string	Unique identifier for this event
`data.userId`	string	User who owns the mailbox
`data.userEmail`	string	User's email address
`data.mailboxId`	string	Mailbox being updated
`data.domain`	string	Domain the mailbox belongs to
`data.email`	string	Full email address
`data.workspaceType`	string	`"GOOGLE"` or `"MICROSOFT"`
`data.updatedFields`	object	Only fields that were changed
`data.updatedFields.firstName`	string	(Optional) Updated first name
`data.updatedFields.lastName`	string	(Optional) Updated last name
`data.updatedFields.userName`	string	(Optional) Updated username
`data.updatedFields.profilePicture`	string	(Optional) Updated profile picture URL

Important notes on `updatedFields`

Only includes changed fields — Don't assume all fields are present

Always check before accessing — Use updatedFields.firstName || oldFirstName

Represents the final state — The values are the new values after the update

Notes

One mailbox.created per mailbox — If you order 5 mailboxes, you'll get 5 separate mailbox.created events

subscriptionId links them — Use subscriptionId to group all mailboxes from the same domain

expiryDate is subscription renewal date — When this date arrives, you'll receive subscription.renewal.* events

Next Steps

Domain Events

Domain registration that must happen first.

Subscription Events

How mailbox subscription renewals work.

Mailbox Warmup

Enroll a mailbox in warmup after it's created.

Overview#

mailbox.order.success#

When it occurs#

Example Payload#

Payload Schema#

mailbox.order.failed#

When it occurs#

Example Payload#

Payload Schema#

mailbox.created#

When it occurs#

Example Payload (Google)#

Example Payload (Microsoft)#

Payload Schema#

mailbox.updated#

When it occurs#

Example Payload#

Payload Schema#

Important notes on updatedFields#

Notes#

Next Steps#

Overview

mailbox.order.success

When it occurs

Example Payload

Payload Schema

mailbox.order.failed

When it occurs

Example Payload

Payload Schema

mailbox.created

When it occurs

Example Payload (Google)

Example Payload (Microsoft)

Payload Schema

mailbox.updated

When it occurs

Example Payload

Payload Schema

Important notes on `updatedFields`

Notes

Next Steps