Managed Mailbox API

Managed mailboxes allow you to create and manage email mailboxes for your domains. You can generate mailbox suggestions, get quotes, and purchase mailboxes.

Get All Mailboxes

Get a list of all managed mailboxes for your organization with filtering, sorting, and pagination.

Query Parameters:

Optional:

• search - string - Search in email address, first name, or last name
• domain - string - Filter by domain ID
• status - string - Filter by status: active, processing, cancelled, cancelled_active, cancelled_expired, expired
• sortBy - string - Sort field: email, firstName, lastName, status, createdAt (default: createdAt)
• sortOrder - string - Sort direction: asc or desc (default: desc)
• limit - number - Number of records to return (default: 50, max: 100)
• offset - number - Number of records to skip (default: 0)

curl -X GET 'https://api.supersend.io/v1/managed-mailboxes?status=active&limit=50&offset=0&sortBy=email&sortOrder=asc' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "mailboxes": [
    {
      "id": "mailbox-uuid",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "computed_status": "active",
      "price": 3.0,
      "createdAt": "2025-11-27T10:30:00Z",
      "is_cancellation_pending": false,
      "current_period_end": "2026-11-27T10:30:00Z",
      "ManagedDomain": {
        "id": "domain-uuid",
        "name": "example.com"
      },
      "Team": {
        "id": "team-uuid",
        "name": "Sales Team"
      }
    }
  ],
  "count": 1,
  "totalCount": 10,
  "limit": 50,
  "offset": 0,
  "hasMore": false,
  "totalPrice": 30.0,
  "processingCount": 0,
  "nextBillingDate": "2026-11-27T10:30:00Z"
}

Generate Mailboxes

Generate mailbox email addresses based on names and domains. Distributes mailboxes across domains using round-robin distribution.

Request Body:

Required:

• domains - array - Array of domain names to generate mailboxes for
• totalCount - number - Total number of mailboxes to generate (min: 1)

Optional:

• names - array - Array of name objects with firstName and lastName (optional). If not provided, random names will be used.

curl -X POST 'https://api.supersend.io/v1/managed-mailboxes/generate' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "domains": ["example.com", "example.org"],
  "names": [
    {
      "firstName": "John",
      "lastName": "Doe"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith"
    }
  ],
  "totalCount": 5
}'

# Response
{
  "mailboxes": [
    {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "domain": "example.com"
    },
    {
      "email": "jane.smith@example.org",
      "firstName": "Jane",
      "lastName": "Smith",
      "domain": "example.org"
    },
    {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "domain": "example.com"
    }
  ]
}

Note: Each domain can have a maximum of 5 mailboxes. The generator will distribute mailboxes across domains using round-robin distribution.

Get Quote

Get pricing quote for mailboxes before purchase. Validates that mailboxes don't already exist and that domain limits are not exceeded.

Request Body:

Required:

• mailboxes - array - Array of mailbox objects with email field (min: 1)

curl -X POST 'https://api.supersend.io/v1/managed-mailboxes/quote' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "mailboxes": [
    {
      "email": "john@example.com"
    },
    {
      "email": "jane@example.com"
    }
  ]
}'

# Response
{
  "pricePerMailbox": 5.0,
  "total": 10.0,
  "count": 2
}

Pricing:

• 1-99 mailboxes: $5.00/month per mailbox
• 100-249 mailboxes: $2.00/month per mailbox
• 250+ mailboxes: $1.50/month per mailbox

Note: If any email addresses already exist or would exceed domain limits (5 mailboxes per domain), the request will return an error.

Purchase Mailboxes

Purchase one or more mailboxes. Creates a Stripe subscription and queues mailboxes for processing.

Request Body:

Required:

• mailboxes - array - Array of mailbox objects with:
  • username - string - Username part of email (before @)
  • firstName - string - First name
  • lastName - string - Last name (optional)
  • domain - string - Domain name
  • signature - string - Email signature (optional)
• paymentMethodId - string - Stripe payment method ID

Optional:

• TeamId - string - Team ID to assign mailboxes to. If not provided, the first available team will be used.

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

# Response
{
  "success": true,
  "message": "Checkout completed successfully. Mailboxes are being processed and will be available shortly.",
  "status": "processing",
  "subscription": {
    "id": "sub_xxxxx",
    "invoice": {
      "id": "in_xxxxx",
      "invoice_pdf": "https://pay.stripe.com/invoice/...",
      "hosted_invoice_url": "https://invoice.stripe.com/...",
      "receipt_number": "1234-5678"
    }
  }
}

Pricing by Provider:

• Google/Outlook mailboxes: $5.00/month per mailbox
• SMTP/Generic mailboxes: $3.00/month per mailbox

Note: Mailboxes are created with pending status and processed asynchronously. The mailbox provider is determined by the domain's mailboxProvider setting.