Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.peeker.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 users[] 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 users[] entries you sent).
cURL
curl -X POST "https://api.peeker.ai/api/partner/v1/swaps/user_names" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "domain_id": "dom_01HZX0D01…",
    "users": [
      { "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…", "status": "created" },
      { "id": "swp_01HZX0SW3…", "type": "user_names", "domain_id": "dom_01HZX0D01…", "status": "created" }
    ]
  }
}
Optional. If you send profile_picture_url, Peeker validates it’s publicly accessible. A private or local URL triggers swap.action_required with the same profile_picture_* reasons that orders raise. 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/api/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 May 14, 2026