Managed Domain API

Interfaces to manage domains

Managed domains allow you to purchase and manage custom domains for email sending. You can check availability, generate suggestions, and purchase domains, or connect a domain you already own and buy mailboxes on it.

ℹ️

V2 API Available

V2 provides standardized responses for listing and retrieving domains.

List Domains

Get all managed domains for your organization.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/domains?team_id=xxx&status=active&managed=internal&search=example&sort_by=name&sort_order=asc&limit=20' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "object": "domain", "id": "domain-uuid", "name": "example.com", "status": "active", "managed": "internal", "provider": "supersend", "registrar": "supersend", "dns_provider": "supersend", "expires_at": "2026-11-27T10:30:00Z", "auto_renew": true, "cancel_at_period_end": false, "dmarc_email": "dmarc@example.com", "active_sender_count": 3, "health": { "is_active": true, "dns_valid": true, "spf_valid": true, "dkim_valid": true, "dmarc_valid": true, "mx_valid": true, "is_blacklisted": false, "last_check": "2025-11-27T10:00:00Z" }, "team_id": "team-uuid", "created_at": "2025-11-27T10:30:00Z", "updated_at": "2025-11-27T10:30:00Z" } ], "pagination": { "total": 5, "limit": 20, "offset": 0, "has_more": false }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

Parameter	Type	Required	Description
`team_id`	string	No	Filter by team ID
`status`	string	No	Filter by status: `pending`, `purchasing`, `purchased`, `setting_up`, `active`, `purchase_failed`, `setup_failed`, `inactive`, `expired`, `cancelled`
`managed`	string	No	Filter by management: `internal` or `external`
`search`	string	No	Search in domain name
`sort_by`	string	No	Sort field: `created_at`, `name`, `status`, `expires_at` (default: `name`)
`sort_order`	string	No	Sort direction: `asc` or `desc` (default: `asc`)
`limit`	number	No	Results per page (default: 50, max: 100)
`offset`	number	No	Pagination offset (default: 0)

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/managed-domains?status=active&limit=50' \
  -H "Authorization: Bearer YOUR_API_KEY"# Response
{
  "domains": [...],
  "count": 5,
  "totalPrice": 65.0,
  "processingCount": 0
}

V1 Query Parameters:

search - Search in domain name

status - Filter: active, processing, cancelled, expired

sortBy - Sort field: name, status, expires_at, mailboxCount

sortOrder - asc or desc

limit / offset - Pagination

Get Domain

Get details for a specific domain, by ID or by name (/v2/domains/example.com). Domains bought through SuperSend show supersend as their provider, registrar and dns_provider. The response also includes setup, the same stage, nameservers, mailboxes and next fields as Verify Domain, without the live lookup.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/domains/domain-uuid' \
  -H "Authorization: Bearer YOUR_API_KEY"# Response (200 OK)
{
  "success": true,
  "data": {
    "object": "domain",
    "id": "domain-uuid",
    "name": "example.com",
    "status": "active",
    "managed": "internal",
    "provider": "supersend",
    "registrar": "supersend",
    "dns_provider": "supersend",
    "expires_at": "2026-11-27T10:30:00Z",
    "auto_renew": true,
    "cancel_at_period_end": false,
    "dmarc_email": "dmarc@example.com",
    "forwarding_address": "forward@example.com",
    "active_sender_count": 3,
    "health": {
      "is_active": true,
      "dns_valid": true,
      "spf_valid": true,
      "dkim_valid": true,
      "dmarc_valid": true,
      "mx_valid": true,
      "is_blacklisted": false,
      "blacklist_reason": null,
      "blacklist_providers": [],
      "errors": [],
      "warnings": [],
      "last_check": "2025-11-27T10:00:00Z",
      "records": {
        "spf": "v=spf1 include:_spf.example.com ~all",
        "dkim": "v=DKIM1; k=rsa; p=...",
        "dmarc": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
        "mx": ["mail.example.com"],
        "nameservers": ["ada.ns.example.net", "bob.ns.example.net"]
      }
    },
    "dns_records": {
      "spf": {...},
      "dkim": {...},
      "dmarc": {...},
      "mx": [...]
    },
    "team": {
      "id": "team-uuid",
      "name": "Sales Team"
    },
    "senders": [
      {
        "id": "sender-uuid",
        "email": "sales@example.com",
        "send_as": "Sales Team",
        "disabled": false,
        "warm": true,
        "warming_stage": 3,
        "health_score": 95,
        "status": "active"
      }
    ],
    "created_at": "2025-11-27T10:30:00Z",
    "updated_at": "2025-11-27T10:30:00Z"
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

Connect a Domain You Own

Bring a domain registered anywhere outside SuperSend into a team, so you can buy mailboxes on it. Connecting is free and changes nothing at your registrar: the domain only needs new nameservers once mailboxes on it are paid for.

Connect it: POST /v2/domains/connect.

Buy mailboxes on it: list it in POST /v2/setup/inbox-checkout like a new domain. It comes back with owned: true and no domain charge; the user pays for the mailboxes through the checkout link.

Set its nameservers: a few minutes after payment, Verify Domain returns the two nameservers to set at your registrar (nameservers.set_to). Replace all of the domain's nameservers with those two. The same instructions are emailed to you.

Wait for them to go live: SuperSend checks every few minutes and creates the mailboxes once the nameservers are live (minutes to 48 hours). They start warming on their own.

⚠️

Use an outreach-only domain

Changing a domain's nameservers moves all of its DNS to SuperSend, including its website and any other email on it. Don't connect your main company domain for cold outreach.

bash

curl -X POST 'https://api.supersend.io/v2/domains/connect' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d 700 dark:text-green-400">'{ "domain": "tryacme.com", "team_id": "team-uuid" }'

# Response (201 Created; 200 with "already_connected": true if it was already in your organization) { "success": true, "data": { "object": "domain_setup", "id": "domain-uuid", "name": "tryacme.com", "managed": "external", "status": "pending", "team_id": "team-uuid", "team": { "id": "team-uuid", "name": "Acme Outbound" }, "stage": "connected", "nameservers": { "change_required": false, "set_to": null, "current": null, "verified": false, "verified_at": null }, "mailboxes": { "total": 0, "active": 0, "in_progress": 0, "failed": 0, "items": [] }, "next": "Connected. No DNS change is needed until you buy mailboxes on it. ...", "already_connected": false }, "request_id": "req_a1b2c3d4e5f6789012345678" }

Returns 409 if the domain is in another SuperSend account (domain_taken) or in another team of your organization (domain_in_other_team).

With the CLI: supersend domains connect --domain tryacme.com.

Verify Domain

Check where a domain stands, by ID or by name. For a connected domain waiting on its nameserver change, the nameservers are looked up live first.

bash

curl -X POST 'https://api.supersend.io/v2/domains/tryacme.com/verify' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": { "object": "domain_setup", "id": "domain-uuid", "name": "tryacme.com", "managed": "external", "status": "awaiting_nameservers", "stage": "awaiting_nameservers", "nameservers": { "change_required": true, "set_to": ["ada.ns.example.net", "bob.ns.example.net"], "current": ["ns1.your-registrar.example", "ns2.your-registrar.example"], "verified": false, "verified_at": null }, "mailboxes": { "total": 2, "active": 0, "in_progress": 2, "failed": 0, "items": [ { "email": "ada@tryacme.com", "provider": "google", "status": "pending" }, { "email": "alan@tryacme.com", "provider": "google", "status": "pending" } ] }, "next": "This domain is registered outside SuperSend. At the registrar where tryacme.com is registered, replace all of its nameservers with: ...", "check": { "checked_at": "2026-10-06T12:00:00.000Z", "looked_up": true } }, "request_id": "req_a1b2c3d4e5f6789012345678" }

`stage`	Meaning
`connected`	Connected; nothing to do until mailboxes are bought on it
`preparing_nameservers`	Mailboxes paid for; the nameservers are ready in a few minutes
`awaiting_nameservers`	Set the nameservers in `nameservers.set_to` at your registrar
`ready`	Nameservers live (or bought through SuperSend); mailboxes being created or live
`setting_up`	Bought through SuperSend and still registering
`unavailable`	Cancelled, expired or failed; can't take new mailboxes

With the CLI: supersend domains verify --domain tryacme.com.

Generate Domain Suggestions (V1)

Generate available domain name suggestions.

bash

curl -X POST 'https://api.supersend.io/v1/managed-domains/generate-suggestions' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rootDomain": "example",
    "count": 10
  }'# Response
{
  "suggestions": [
    { "name": "getexample.com", "available": true },
    { "name": "tryexample.com", "available": true },
    { "name": "examplehq.com", "available": true }
  ]
}

Check Domain Availability (V1)

Check if a domain is available for purchase.

bash

curl -X POST 'https://api.supersend.io/v1/managed-domains/check-availability' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com" }'

# Response { "domain": "example.com", "available": true, "price": 13.0, "currency": "USD" }

Purchase Domain (V1)

Purchase an available domain.

bash

curl -X POST 'https://api.supersend.io/v1/managed-domains/purchase' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com" }'

# Response { "success": true, "domain": { "id": "domain-uuid", "name": "example.com", "status": "processing" }, "message": "Domain purchase initiated" }

Domain Status Values

Status	Description
`processing`	Domain purchase in progress
`active`	Domain is active and ready
`cancelled`	Cancellation requested
`cancelled_active`	Cancelled but still active until expiry
`cancelled_expired`	Cancelled and expired
`expired`	Domain has expired
`awaiting_nameservers`	Connected domain waiting for its owner to set the nameservers SuperSend gave

V1 vs V2 Endpoint Mapping

Action	V1 Endpoint	V2 Endpoint
List	`GET /v1/managed-domains`	`GET /v2/domains`
Get	`GET /v1/managed-domains/:id`	`GET /v2/domains/:id`
Suggestions	`POST /v1/managed-domains/generate-suggestions`	V1 only
Availability	`POST /v1/managed-domains/check-availability`	V1 only
Purchase	`POST /v1/managed-domains/purchase`	V1 only
Connect your own domain	`POST /v1/managed-domains/connect-external`	`POST /v2/domains/connect`
Check nameservers	`POST /v1/managed-domains/:id/verify-nameservers`	`POST /v2/domains/:id/verify`