Skip to main content
Different from a domain swap - here the domain stays, but the first name, last name, or email username we use on the inbox changes. Use it when:
  • A customer rotates the team that sends from a domain (Alex/Sam left, Jordan/Riley take over).
  • A customer rebrands and wants different display names on warmup-aged inboxes.
  • The user’s names are wrong, or the generated email username needs a clean fix.
The result: each inbox on the domain gets a new first/last name, optional profile picture, and email username when needed. Warmup history stays intact. To replace the domain itself, use How to implement domain swaps instead.

​
Steps in detail

1. Submit the new name list

POST /swaps/user_names takes the existing domain_id and a personas[] list. The response is a batch of swp_… rows - one per inbox being renamed - each with the same swap.* event lifecycle as a domain swap. The number of rows in the response equals the number of inboxes on the domain (not the number of personas[] entries you sent).
cURL
curl -X POST "https://api.peeker.ai/partner/v1/swaps/user_names" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "domain_id": "dom_01HZX0D01…",
    "personas": [
      { "first_name": "Jordan", "last_name": "Pham", "profile_picture_url": "https://cdn.acme.com/jordan.jpg" },
      { "first_name": "Riley",  "last_name": "Wu",   "profile_picture_url": "https://cdn.acme.com/riley.jpg"  }
    ]
  }'
201 Created
{
	"data": {
		"swaps": [
			{
				"id": "swp_01HZX0SW2…",
				"type": "user_names",
				"domain_id": "dom_01HZX0D01…",
				"replacement_domain": null,
				"status": "created",
				"created_at": "2026-05-08T12:00:00Z"
			},
			{
				"id": "swp_01HZX0SW3…",
				"type": "user_names",
				"domain_id": "dom_01HZX0D01…",
				"replacement_domain": null,
				"status": "created",
				"created_at": "2026-05-08T12:00:00Z"
			}
		]
	}
}
Every persona includes the profile_picture_url key. Use a public URL, null, or "". A private or local URL triggers swap.action_required with profile_picture_not_accessible. See Best practices → Pending actions.
Poll GET /swaps/{id} for any swp_… row, or listen for its swap.* webhooks. Each row moves through:
cURL
curl -X GET "https://api.peeker.ai/partner/v1/swaps/swp_01HZX0SW…" \
  -H "Authorization: Bearer pk_test_<your-key>"

created  →  in_progress  →  completed
                       ↘  failed
                       ↘  action_required
A batch can have some rows complete while others stall on profile-picture issues. Resolve those one inbox at a time.
  • The domain itself - DNS, MX records, Cloudflare zone, registrar.
  • Warmup history on each inbox - the inbox’s reputation isn’t reset by the rename.
  • The order, the workspace, and the customer’s link to both.
What changes:
  • Display name on outgoing mail.
  • The local-part of the inbox address (e.g. alex@… → jordan@…) only if the rename changes which local-part Peeker generates. Most renames change the display only.

​
What’s next

How to implement domain swaps

Replace the domain itself, not just the people on it.

Best practices

Pending actions, webhook hygiene, idempotent retries.
Last modified on June 29, 2026