Update Domain Name

🔁 Use this endpoint to request replacing an existing domain with a new one.

⚠️ This creates a pending request, same as /swap-redirect and /swap-sender-name — it does not take effect immediately. Our team reviews and applies it.

🔑 Authentication

Requires a valid API token.

POST /api/v1/swap-domain/:old_domain

🔑 Path Parameters

`old_domain` (required)

The domain you want to replace. Must already exist in your account.

🔑 Query Parameters

`organization_id` (required)

Your organization's ID. The domain must belong to this organization.

`provider` (required)

Where the new domain comes from:

"scaledmail" — The new domain must already exist in your unassigned purchased-domains inventory. Check with Get Purchased Domains (?available=true) first.

"other" — The new domain is hosted elsewhere (e.g. Namecheap, Porkbun, GoDaddy). You may optionally supply hosting credentials.

📥 Request Body Parameters

`new_domain` (required)

The replacement domain name.

{ "new_domain": "newbrand.com" }

Must be a valid domain format (e.g. "newbrand.com").

`hosting` (optional, `provider=other` only)

Credentials for the registrar/host of the new domain, if you'd like our team to have them for setup.

"hosting": {
  "provider": "Namecheap",
  "username": "your-username",
  "password": "your-password",
  "link": "https://namecheap.com"
}

provider, username, password are all required together if hosting is included at all.

link is optional but cannot be empty if provided.

provider must be a supported registrar name (e.g. "Namecheap", "Porkbun", "GoDaddy", "Cloudflare" — see error response below for the full list).

Not accepted when provider=scaledmail — the request is rejected if hosting is present.

📋 Example Requests

Example 1 — Replace with a ScaledMail-purchased domain

POST /api/v1/swap-domain/outreach-one.com?organization_id=recXXXXXXXXXXXXXX&provider=scaledmail

{
  "new_domain": "outreach-fresh.com"
}

Example 2 — Replace with an externally-hosted domain

POST /api/v1/swap-domain/outreach-one.com?organization_id=recXXXXXXXXXXXXXX&provider=other

{
  "new_domain": "mybrand.io",
  "hosting": {
    "provider": "Porkbun",
    "username": "user@company.com",
    "password": "yourpassword",
    "link": "https://porkbun.com"
  }
}

✅ Response

{
  "message": "Domain Swap Requested"
}

⚠️ Error Responses

Invalid provider

{ "error": "Invalid provider. Must be 'scaledmail' or 'other'" }

Hosting not allowed for this provider

{ "error": "Hosting cannot be provided when provider is 'scaledmail' or 'buy'" }

Invalid hosting provider

{ "error": "Invalid hosting provider", "validProviders": ["Porkbun", "Namecheap", "Godaddy", "HostGator", "Bigrock", "Spaceship", "Dynadot", "Ionos", "Cloudflare", "DnSimple", "Scaledmail", "Other"] }

Invalid domain format

{ "error": "Invalid domain format" }

Domain not found

{ "error": "Domain not found" }

New domain not available (`provider=scaledmail`)

{ "error": "Domain not available or already in use" }

Conflicting pending request already exists

{ "error": "Cannot create domain swap request. Domain \"outreach-one.com\" already has a pending Domain Name change request (Status: New Order)" }

ℹ️ Notes

This endpoint cannot be used by test accounts.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

🔑 Authentication#

🔑 Path Parameters#

old_domain (required)#

🔑 Query Parameters#

organization_id (required)#

provider (required)#

📥 Request Body Parameters#

new_domain (required)#

hosting (optional, provider=other only)#

📋 Example Requests#

Example 1 — Replace with a ScaledMail-purchased domain#

Example 2 — Replace with an externally-hosted domain#

✅ Response#

⚠️ Error Responses#

Invalid provider#

Hosting not allowed for this provider#

Invalid hosting provider#

Invalid domain format#

Domain not found#

New domain not available (provider=scaledmail)#

Conflicting pending request already exists#

ℹ️ Notes#

Request

Responses