Update Sender Name

✉️ Use this endpoint to request a change to the sender names (and optionally the mailbox aliases/email addresses) on an existing domain's mailboxes.

⚠️ This creates a pending request, same as /swap-domain and /swap-redirect — it does not change anything immediately. Our team reviews and applies it.

🔑 Authentication

Requires a valid API token.

POST /api/v1/swap-sender-name/:old_domain

🔑 Path Parameters

`old_domain` (required)

The domain whose mailbox sender names you want to update. Must already exist in your account and have mailboxes on it.

🔑 Query Parameters

`organization_id` (required)

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

`mode` (required)

Controls whether the mailbox alias (email address) also changes. Must be one of:

"name_only" — Only the sender's display name changes. Every existing mailbox alias is kept exactly as-is — no re-warming needed.

"name_and_alias" — A new alias is generated per mailbox too. The old mailbox is deleted and a new one is created, which needs 2-4 days to warm up before sending at full volume.

There's no default — you must pass one explicitly, since the two options have very different consequences for deliverability.

📥 Request Body Parameters

`sender_names` (required)

An array of { first_name, last_name } objects, distributed evenly across the domain's existing mailboxes in order.

"sender_names": [
  { "first_name": "John", "last_name": "Doe" },
  { "first_name": "Jane", "last_name": "Smith" }
]

Must be a non-empty array.

Each entry requires both first_name and last_name.

Sender names are spread evenly across the domain's existing mailboxes — you don't need to know the exact count, but sender_names cannot have more entries than the domain has mailboxes (e.g. a Google domain with 2 mailboxes accepts at most 2 sender names).

📋 Example Requests

Example 1 — `mode=name_only`: rename senders, keep every alias

Only the display name on each mailbox changes — the email addresses stay exactly the same, so there's no re-warming.

Example 2 — `mode=name_and_alias`: one sender for every mailbox

A single sender name is used to generate a fresh alias for every mailbox on the domain — old mailboxes are deleted, new ones need 2-4 days to warm up.

Example 3 — `mode=name_and_alias`: multiple senders split across mailboxes

If the domain has, say, 6 mailboxes and you pass 3 sender names, each sender gets ~2 mailboxes' worth of freshly-generated aliases.

✅ Response

{
  "message": "Sender Name Swap Requested"
}

⚠️ Error Responses

Invalid domain format

{ "error": "Invalid domain format" }

Missing or invalid `mode`

{ "error": "mode query param is required and must be 'name_only' or 'name_and_alias'" }

Missing or invalid `sender_names`

{ "error": "sender_names must be a non-empty array of { first_name, last_name }" }

Domain not found

{ "error": "Domain not found" }

Domain has no mailboxes

{ "error": "This domain has no mailboxes to rename" }

More `sender_names` than the domain has mailboxes

{ "error": "outreach-one.com has 2 mailboxes, but 4 sender_names were passed -- sender_names cannot exceed the domain's mailbox count" }

Couldn't generate enough unique aliases (`name_and_alias` mode)

{ "error": "Error generating aliases for John Doe: we cannot create 5 aliases. Kindly try other name or lower the number of aliases" }

Conflicting pending request already exists

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

ℹ️ Notes

mode is a query parameter, not a body field — pass it in the URL alongside organization_id.

Use mode=name_only whenever you just want a display-name refresh without affecting deliverability or triggering a warm-up period.

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)#

mode (required)#

📥 Request Body Parameters#

sender_names (required)#

📋 Example Requests#

Example 1 — mode=name_only: rename senders, keep every alias#

Example 2 — mode=name_and_alias: one sender for every mailbox#

Example 3 — mode=name_and_alias: multiple senders split across mailboxes#

✅ Response#

⚠️ Error Responses#

Invalid domain format#

Missing or invalid mode#

Missing or invalid sender_names#

Domain not found#

Domain has no mailboxes#

More sender_names than the domain has mailboxes#

Couldn't generate enough unique aliases (name_and_alias mode)#

Conflicting pending request already exists#

ℹ️ Notes#

Request

Responses