Managed Mailbox API

Interfaces to manage mailboxes

Managed mailboxes are email accounts that can be purchased and managed through SuperSend. You can generate mailbox suggestions, get quotes, purchase mailboxes, and manage their lifecycle.

ℹ️

V1 API Only

Managed mailbox operations are available in V1 API only.

List Mailboxes

Get all managed mailboxes for your organization with filtering and pagination.

bash

curl -X GET 'https://api.supersend.io/v1/managed-mailboxes?search=john&domain=example.com&status=active&sortBy=createdAt&sortOrder=desc&limit=50&offset=0' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "mailboxes": [ { "id": "mailbox-uuid", "email": "john@example.com", "firstName": "John", "lastName": "Doe", "status": "active", "computed_status": "active", "provider": "ss-google", "customerPrice": 5.0, "price": 1.5, "autoRenew": true, "cancel_at_period_end": false, "cancelled_at": null, "current_period_end": 1735689600, "is_cancellation_pending": false, "ManagedDomain": { "id": "domain-uuid", "name": "example.com" }, "Team": { "id": "team-uuid", "name": "Sales Team" }, "createdAt": "2025-01-01T00:00:00Z", "updatedAt": "2025-01-15T00:00:00Z" } ], "count": 1, "totalCount": 10, "limit": 50, "offset": 0, "hasMore": false, "totalPrice": 50.0, "processingCount": 2, "nextBillingDate": "2025-02-01T00:00:00Z" }

Query Parameters:

Parameter	Type	Required	Description
`search`	string	No	Search in email, first name, or last name
`domain`	string	No	Filter by domain ID
`status`	string	No	Filter by status: `active`, `processing`, `cancelled`, `cancelled_active`, `cancelled_expired`, `pending`, `inactive`, `error`, `expired`
`sortBy`	string	No	Sort field: `email`, `firstName`, `lastName`, `status`, `createdAt` (default: `createdAt`)
`sortOrder`	string	No	Sort direction: `asc` or `desc` (default: `desc`)
`limit`	number	No	Results per page (default: 50, max: 100)
`offset`	number	No	Pagination offset (default: 0)

Response Fields:

computed_status: Computed status that accounts for cancellation state (active, cancelled_active, cancelled_expired, etc.)

customerPrice: Price customer pays per mailbox (org-specific or global pricing)

price: Cost price from provider

is_cancellation_pending: Boolean indicating if cancellation is pending

totalPrice: Total monthly cost of all active mailboxes

processingCount: Number of mailboxes in processing states

nextBillingDate: Next billing date across all active mailboxes

Generate Mailbox Suggestions

Generate suggested mailbox email addresses based on domains and names.

bash

curl -X POST 'https://api.supersend.io/v1/managed-mailboxes/generate' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["example.com", "test.com"],
    "names": [
      {"firstName": "John", "lastName": "Doe"},
      {"firstName": "Jane", "lastName": "Smith"}
    ],
    "totalCount": 5
  }'# Response (200 OK)
{
  "mailboxes": [
    {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "domain": "example.com"
    },
    {
      "email": "jane.smith@test.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "domain": "test.com"
    }
  ]
}

Request Parameters:

Parameter	Type	Required	Description
`domains`	array	Yes	Array of domain names
`names`	array	No	Array of name objects with `firstName` and `lastName`
`totalCount`	number	Yes	Total number of mailboxes to generate (1-250)

Note:

Each domain can have up to 5 mailboxes

If names array is provided, it cycles through names to reach totalCount

If names is empty, uses random popular names

Email addresses are generated using variations: firstname.lastname, firstname, f.lastname, etc.

Automatically adds numbers if variations conflict with existing mailboxes

Get Quote

Get pricing quote for mailboxes before purchase.

bash

curl -X POST 'https://api.supersend.io/v1/managed-mailboxes/quote' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mailboxes": [
      {"email": "john@example.com"},
      {"email": "jane@example.com"}
    ]
  }'# Response (200 OK)
{
  "pricePerMailbox": 5.0,
  "total": 10.0,
  "count": 2
}

Request Parameters:

Parameter	Type	Required	Description
`mailboxes`	array	Yes	Array of mailbox objects with `email` field (min: 1)

Pricing:

Mailboxes: $5.00 per month per mailbox (all providers: Google, Outlook, Private SMTP)

Domains: $13 per year per domain

This is standard pricing that applies to all customers. Enterprise customers may have custom pricing arrangements.

Errors:

Returns 409 if any email addresses already exist

Returns 400 if domain would exceed 5 mailbox limit

Purchase Mailboxes

Purchase mailboxes and create Stripe subscription.

bash

curl -X POST 'https://api.supersend.io/v1/managed-mailboxes/purchase' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mailboxes": [ { "username": "john", "firstName": "John", "lastName": "Doe", "domain": "example.com", "signature": "John Doe\nSales Team", "provider": "google" } ], "TeamId": "team-uuid", "paymentMethodId": "pm_xxx" }'

# Response (200 OK) { "success": true, "message": "Checkout completed successfully. Mailboxes are being processed and will be available shortly.", "status": "processing", "subscription": { "id": "sub_xxx", "invoice": { "id": "in_xxx", "invoice_pdf": "https://...", "hosted_invoice_url": "https://...", "receipt_number": "1234" } } }

Request Parameters:

Parameter	Type	Required	Description
`mailboxes`	array	Yes	Array of mailbox objects (see below)
`TeamId`	string	No	Team ID (auto-assigned to user's first team if not provided)
`paymentMethodId`	string	Yes	Stripe payment method ID

Mailbox Object:

Field	Type	Required	Description
`username`	string	Yes	Username part of email (before @)
`firstName`	string	Yes	First name
`lastName`	string	No	Last name
`domain`	string	Yes	Domain name
`signature`	string	No	Email signature
`provider`	string	No	Provider: `google`, `outlook`, `smtp`, or `generic` (default: `generic`)

Note:

Mailboxes are queued for async processing after purchase

Stripe subscription is created immediately

Mailboxes start with status: "pending" and transition to active when ready

Pricing is org-specific (can be customized per organization)

Update Mailbox

Update mailbox details (name, password, signature, auto-renew).

bash

curl -X PUT 'https://api.supersend.io/v1/managed-mailboxes/mailbox-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Jane", "lastName": "Smith", "password": "newpassword123", "signature": "Jane Smith\nMarketing Team", "autoRenew": true, "customerPrice": 5.0 }'

# Response (200 OK) { "success": true, "message": "Mailbox updated successfully", "mailbox": { "id": "mailbox-uuid", "email": "john@example.com", "firstName": "Jane", "lastName": "Smith", ... } }

Request Parameters:

Parameter	Type	Required	Description
`firstName`	string	No	First name
`lastName`	string	No	Last name
`password`	string	No	Password (min: 8 characters)
`signature`	string	No	Email signature
`autoRenew`	boolean	No	Auto-renew subscription
`customerPrice`	number	No	Custom customer price (admin only)

Note:

Password updates sync to Hosted Email provider

Name updates sync to Inboxkit provider

Signature/password updates sync to all Senders with matching email

Empty strings are normalized to null

Cancel Mailbox

Cancel a mailbox subscription (cancels at period end).

bash

curl -X DELETE 'https://api.supersend.io/v1/managed-mailboxes/mailbox-uuid/cancel' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "message": "Mailbox subscription cancelled successfully. Your mailbox will remain active until the end of the current billing period.", "mailbox": { "id": "mailbox-uuid", "email": "john@example.com", "cancel_at_period_end": true, "cancelled_at": "2025-01-15T00:00:00Z", ... } }

Note:

Mailbox remains active until current billing period ends

Stripe subscription is cancelled at period end

Prorated amount is credited to account

If last mailbox in subscription item, entire subscription is cancelled

If other mailboxes share subscription item, quantity is reduced

Inboxkit mailboxes are cancelled in Inboxkit

Hosted Email mailboxes are deleted immediately

Reactivate Mailbox

Reactivate a cancelled mailbox subscription (before period end).

bash

curl -X POST 'https://api.supersend.io/v1/managed-mailboxes/mailbox-uuid/reactivate' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "message": "Mailbox subscription reactivated successfully. Your subscription will continue automatically.", "mailbox": { "id": "mailbox-uuid", "email": "john@example.com", "cancel_at_period_end": false, "cancelled_at": null, ... } }

Note:

Only works if mailbox is cancelled but not yet expired

Removes cancel_at_period_end flag from Stripe subscription

Clears cancellation metadata from mailbox

Subscription continues automatically after period end

Mailbox Statuses

Status	Description
`pending`	Mailbox is being created
`processing`	Mailbox is being set up
`active`	Mailbox is active and ready to use
`inactive`	Mailbox is inactive
`cancelled`	Mailbox subscription is cancelled
`cancelled_active`	Cancelled but still active until period end
`cancelled_expired`	Cancelled and period has ended
`expired`	Mailbox subscription has expired
`error`	Error occurred during setup

Mailbox Providers

Provider	Description	Purchase Source
`ss-google`	Google Workspace mailbox	Inboxkit
`ss-outlook`	Microsoft 365 mailbox	Inboxkit
`ss-generic`	Generic mailbox	Tucows Hosted Mail
`ss-private-smtp`	Private SMTP mailbox	Mission Inbox IBX

Domain Limits

Each managed domain can have up to 5 mailboxes

Mailboxes are distributed round-robin across domains

If a domain reaches 5 mailboxes, new mailboxes are assigned to other domains