API Reference

Programmatically manage domains, mailboxes, and aliases. Integrate ClubSMTP email hosting into your own applications and automated workflows.

Overview

The ClubSMTP REST API lets you provision and manage email infrastructure using standard HTTP methods. All request and response bodies use JSON. The API is versioned — the current version is v1.

You can create and manage API keys from Settings → API Keys.

Base URL: https://api.clubsmtp.com/

Authentication

All requests must include your secret API key as a Bearer token in the Authorization header. Never expose your secret key in client-side code or public repositories.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

HTTPS required. All API requests must be made over HTTPS. Plain HTTP requests are rejected with 403 Forbidden.

API Key Scopes

When creating an API key you define its scope — the paths and methods the key is permitted to call. Scope entries use the format METHOD:/path and support wildcards:

GET:/v1/domains
POST:/v1/mailboxes
*:*

A request that does not match any scope entry is rejected with 403 Forbidden.

CIDR Restrictions

Optionally restrict an API key to specific IP ranges by adding CIDR blocks (e.g. 203.0.113.0/24). If any CIDR blocks are configured, requests from IPs outside those ranges are rejected with 403 Forbidden.

API Key Expiry

Keys may be given an optional expiry date. Once expired the key is permanently deactivated and returns 401 Unauthorized.

Rate Limiting

The API enforces a leaky bucket rate limit. Each key has a configurable request-per-minute ceiling (default: 60 requests/min). When the limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 8

Errors

Every response includes an errors array. On success it is empty. On failure it contains one or more error objects:

{
  "errors": [
    {
      "message": "Domain not found.",
      "type": "invalid_request_error"
    }
  ]
}

type	HTTP status	Meaning
auth_error	401	Missing, invalid, or expired API key
security_error	403	HTTPS required, IP blocked, out-of-scope request, or account not found
invalid_request_error	400	Missing or invalid parameter, resource not found
rate_limit_error	429	Too many requests — check Retry-After header
api_error	500	Unexpected server-side error

Ping

Use the ping endpoint to verify connectivity and confirm your API key is valid.

GET /v1/ping

Returns a timestamp. No parameters required.

curl https://api.clubsmtp.com/v1/ping \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "timestamp": "Mon, 21 Apr 2026 12:00:00 GMT",
  "errors": []
}

Domains

A domain represents an email domain you host through ClubSMTP (e.g. example.com). Each domain has six associated DNS records that must be configured at your DNS registrar for email delivery to function correctly.

GET /v1/domains

Returns all domains belonging to the account, each with their DNS record statuses.

curl https://api.clubsmtp.com/v1/domains \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
      "name": "example.com",
      "created_at": "2026-01-15T09:00:00.000000Z",
      "dns_records": [
        {
          "uuid": "018f1a2b-3c4d-7e5f-a6b7-000000000001",
          "record_type": "MX",
          "expected_value": "10 mail.example.com.",
          "actual_value": "10 mail.example.com.",
          "status": 2,
          "last_checked_at": "2026-04-21T08:00:00.000000Z"
        }
      ]
    }
  ],
  "errors": []
}

DNS record status values: 1 = Pending, 2 = OK, 3 = Fail.

DNS record types seeded on creation: MX, SPF, DKIM, DMARC, autoconfig, autodiscover.

POST /v1/domains

Adds a new domain to the account and seeds the six required DNS record rows.

Parameter	Type		Description
name	string	required	The fully-qualified domain name (e.g. example.com). Must be unique across all accounts.

curl -X POST https://api.clubsmtp.com/v1/domains \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}'

{
  "domain": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "name": "example.com",
    "created_at": "2026-04-21T14:00:00.000000Z",
    "dns_records": [
      { "uuid": "...", "record_type": "MX",          "expected_value": null, "actual_value": null, "status": 1, "last_checked_at": null },
      { "uuid": "...", "record_type": "SPF",         "expected_value": null, "actual_value": null, "status": 1, "last_checked_at": null },
      { "uuid": "...", "record_type": "DKIM",        "expected_value": null, "actual_value": null, "status": 1, "last_checked_at": null },
      { "uuid": "...", "record_type": "DMARC",       "expected_value": null, "actual_value": null, "status": 1, "last_checked_at": null },
      { "uuid": "...", "record_type": "autoconfig",  "expected_value": null, "actual_value": null, "status": 1, "last_checked_at": null },
      { "uuid": "...", "record_type": "autodiscover","expected_value": null, "actual_value": null, "status": 1, "last_checked_at": null }
    ]
  },
  "errors": []
}

GET /v1/domains/:uuid

Returns a single domain by UUID, including all DNS record statuses.

curl https://api.clubsmtp.com/v1/domains/018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "domain": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "name": "example.com",
    "created_at": "2026-01-15T09:00:00.000000Z",
    "dns_records": [ ... ]
  },
  "errors": []
}

DELETE /v1/domains/:uuid

Permanently deletes a domain and cascades the deletion to all associated DNS records, email addresses, mailboxes, and aliases. This action cannot be undone.

curl -X DELETE https://api.clubsmtp.com/v1/domains/018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "success": true,
  "errors": []
}

Mailboxes

A mailbox is a full email account (IMAP/SMTP) hosted on the ClubSMTP mail server. Each mailbox is associated with an email address on one of your domains.

GET /v1/mailboxes

Returns all mailboxes for the account. Optionally filter by domain.

Parameter	Type		Description
domain_uuid	string (query)	optional	Filter results to mailboxes on a specific domain.

curl "https://api.clubsmtp.com/v1/mailboxes?domain_uuid=018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3" \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4",
      "address": "alice@example.com",
      "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
      "domain": "example.com",
      "storage_gb": 10,
      "enabled": true,
      "created_at": "2026-02-01T10:00:00.000000Z",
      "updated_at": "2026-02-01T10:00:00.000000Z"
    }
  ],
  "errors": []
}

POST /v1/mailboxes

Creates a new mailbox on the mail server. The password is transmitted securely and never stored in plaintext.

Parameter	Type		Description
domain_uuid	string	required	UUID of the domain to create the mailbox on.
local_part	string	required	The portion of the address before the @ sign (e.g. alice).
password	string	required	Plaintext password for IMAP/SMTP authentication.
storage_gb	integer	optional	Storage quota in gigabytes. Defaults to 10. Minimum 1.

curl -X POST https://api.clubsmtp.com/v1/mailboxes \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "local_part": "alice",
    "password": "correct-horse-battery-staple",
    "storage_gb": 20
  }'

{
  "mailbox": {
    "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4",
    "address": "alice@example.com",
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "domain": "example.com",
    "storage_gb": 20,
    "enabled": true,
    "created_at": "2026-04-21T14:30:00.000000Z",
    "updated_at": "2026-04-21T14:30:00.000000Z"
  },
  "errors": []
}

GET /v1/mailboxes/:uuid

Returns a single mailbox by UUID.

curl https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "mailbox": {
    "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4",
    "address": "alice@example.com",
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "domain": "example.com",
    "storage_gb": 20,
    "enabled": true,
    "created_at": "2026-04-21T14:30:00.000000Z",
    "updated_at": "2026-04-21T14:30:00.000000Z"
  },
  "errors": []
}

PATCH /v1/mailboxes/:uuid

Updates a mailbox's enabled state or storage quota. Only include the fields you wish to change.

Parameter	Type		Description
enabled	boolean	optional	Set to false to suspend the mailbox, true to re-enable it.
storage_gb	integer	optional	New storage quota in gigabytes. Minimum 1.

curl -X PATCH https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4 \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

{
  "mailbox": {
    "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4",
    "address": "alice@example.com",
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "domain": "example.com",
    "storage_gb": 20,
    "enabled": false,
    "created_at": "2026-04-21T14:30:00.000000Z",
    "updated_at": "2026-04-21T15:00:00.000000Z"
  },
  "errors": []
}

DELETE /v1/mailboxes/:uuid

Permanently deletes a mailbox from the mail server, removing all stored email. This action cannot be undone.

curl -X DELETE https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "success": true,
  "errors": []
}

Mailbox Filters

Each mailbox has an independent whitelist and blacklist of pattern strings used by the mail server to accept or reject incoming messages. Patterns are matched against sender addresses.

GET /v1/mailboxes/:uuid/whitelist

Returns all whitelist entries for a mailbox, ordered by creation date.

curl https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4/whitelist \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "01ab2c3d-4e5f-7a6b-c7d8-e9f0a1b2c3d4",
      "pattern": "*@trusted.com",
      "created_at": "2026-04-01T08:00:00.000000Z"
    }
  ],
  "errors": []
}

POST /v1/mailboxes/:uuid/whitelist

Adds a pattern to the mailbox whitelist.

Parameter	Type		Description
pattern	string	required	Sender pattern to whitelist (e.g. *@trusted.com or noreply@example.com).

curl -X POST https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4/whitelist \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "*@trusted.com"}'

{
  "entry": {
    "uuid": "01ab2c3d-4e5f-7a6b-c7d8-e9f0a1b2c3d4",
    "pattern": "*@trusted.com",
    "created_at": "2026-04-21T15:10:00.000000Z"
  },
  "errors": []
}

DELETE /v1/mailboxes/:uuid/whitelist/:entryUuid

Removes a pattern from the mailbox whitelist.

curl -X DELETE https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4/whitelist/01ab2c3d-4e5f-7a6b-c7d8-e9f0a1b2c3d4 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "success": true,
  "errors": []
}

GET /v1/mailboxes/:uuid/blacklist

Returns all blacklist entries for a mailbox, ordered by creation date.

curl https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4/blacklist \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "01bc2d3e-4f5a-7b6c-d7e8-f9a0b1c2d3e4",
      "pattern": "*@spam-domain.net",
      "created_at": "2026-03-15T12:00:00.000000Z"
    }
  ],
  "errors": []
}

POST /v1/mailboxes/:uuid/blacklist

Adds a pattern to the mailbox blacklist.

Parameter	Type		Description
pattern	string	required	Sender pattern to block (e.g. *@spam-domain.net).

curl -X POST https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4/blacklist \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "*@spam-domain.net"}'

{
  "entry": {
    "uuid": "01bc2d3e-4f5a-7b6c-d7e8-f9a0b1c2d3e4",
    "pattern": "*@spam-domain.net",
    "created_at": "2026-04-21T15:20:00.000000Z"
  },
  "errors": []
}

DELETE /v1/mailboxes/:uuid/blacklist/:entryUuid

Removes a pattern from the mailbox blacklist.

curl -X DELETE https://api.clubsmtp.com/v1/mailboxes/019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4/blacklist/01bc2d3e-4f5a-7b6c-d7e8-f9a0b1c2d3e4 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "success": true,
  "errors": []
}

Aliases

An alias is a forwarding address that routes incoming mail to one or more mailboxes. The alias address is not a mailbox itself — it has no storage and cannot send mail directly.

GET /v1/aliases

Returns all aliases across all domains for the account.

curl https://api.clubsmtp.com/v1/aliases \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "01cd3e4f-5a6b-7c8d-e9f0-a1b2c3d4e5f6",
      "address": "info@example.com",
      "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
      "domain": "example.com",
      "forwarding_to": [
        { "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4", "address": "alice@example.com" }
      ],
      "created_at": "2026-03-01T09:00:00.000000Z",
      "updated_at": "2026-03-01T09:00:00.000000Z"
    }
  ],
  "errors": []
}

POST /v1/aliases

Creates a forwarding alias that routes mail to one or more mailboxes.

Parameter	Type		Description
domain_uuid	string	required	UUID of the domain for the alias address.
local_part	string	required	The local part of the alias address (e.g. info).
mailbox_uuids	array	required	Array of mailbox UUIDs to forward mail to. Must be non-empty.

curl -X POST https://api.clubsmtp.com/v1/aliases \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "local_part": "info",
    "mailbox_uuids": ["019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4"]
  }'

{
  "alias": {
    "uuid": "01cd3e4f-5a6b-7c8d-e9f0-a1b2c3d4e5f6",
    "address": "info@example.com",
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "domain": "example.com",
    "forwarding_to": [
      { "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4", "address": "alice@example.com" }
    ],
    "created_at": "2026-04-21T15:30:00.000000Z",
    "updated_at": "2026-04-21T15:30:00.000000Z"
  },
  "errors": []
}

GET /v1/aliases/:uuid

Returns a single alias by UUID, including the list of mailboxes it forwards to.

curl https://api.clubsmtp.com/v1/aliases/01cd3e4f-5a6b-7c8d-e9f0-a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "alias": {
    "uuid": "01cd3e4f-5a6b-7c8d-e9f0-a1b2c3d4e5f6",
    "address": "info@example.com",
    "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "domain": "example.com",
    "forwarding_to": [
      { "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4", "address": "alice@example.com" }
    ],
    "created_at": "2026-03-01T09:00:00.000000Z",
    "updated_at": "2026-03-01T09:00:00.000000Z"
  },
  "errors": []
}

DELETE /v1/aliases/:uuid

Permanently removes an alias from the mail server. The forwarding mailboxes are not affected.

curl -X DELETE https://api.clubsmtp.com/v1/aliases/01cd3e4f-5a6b-7c8d-e9f0-a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "success": true,
  "errors": []
}

Webhook Events

ClubSMTP can deliver real-time notifications to your HTTPS endpoints when objects change. Configure webhook endpoints from Settings → Webhooks. Each delivery includes a signed JSON payload with an id, type, created timestamp, and a data.object containing the affected resource.

Webhook deliveries are queued and retried automatically on failure. Respond with 2xx within 30 seconds to acknowledge receipt.

Event type	Trigger
domain.created	A new domain was added to the account
domain.deleted	A domain was permanently deleted
domain.dns_status_changed	A DNS record's verification status changed
mailbox.created	A new mailbox was provisioned
mailbox.updated	Mailbox settings (e.g. storage quota) were changed
mailbox.enabled	A suspended mailbox was re-enabled
mailbox.disabled	A mailbox was suspended
mailbox.deleted	A mailbox was permanently deleted
alias.created	A new forwarding alias was created
alias.deleted	A forwarding alias was deleted
invite.created	An invitation was sent to a new user
invite.accepted	An invited user accepted and activated their account
invite.expired	An invitation expired before being accepted
invoice.created	A new invoice was generated on the account
invoice.paid	An invoice was successfully paid

Example payload

{
  "id": "01de4f5a-6b7c-8d9e-f0a1-b2c3d4e5f6a7",
  "type": "mailbox.created",
  "created": 1745244600,
  "data": {
    "object": {
      "uuid": "019a2b3c-4d5e-7f6a-b7c8-d9e0f1a2b3c4",
      "address": "alice@example.com",
      "domain_uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
      "domain": "example.com",
      "storage_gb": 20,
      "enabled": true,
      "created_at": "2026-04-21T14:30:00.000000Z",
      "updated_at": "2026-04-21T14:30:00.000000Z"
    }
  }
}