---
title: "Bulk replace email usernames (destructive)"
method: POST
path: "/v1/email-users/replace"
tags: ["Email Users"]
---

# Bulk replace email usernames (destructive)

`POST /v1/email-users/replace`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/email-users/replace`
- Auth: HTTP bearer

Replace the local part (username) of up to 100 mailboxes. A mailbox
cannot be renamed on the mail server, so each replacement DELETES the
old mailbox — **all messages in it are permanently lost and cannot be
recovered** — and recreates it on the same domain with the new
username and a fresh password. Warming restarts from scratch (it is
automatically re-enabled when the old mailbox had it). Works for
pre-warmed mailboxes too (the pre-warmed flag and billing pool carry
over 1:1). Processing is asynchronous; poll the returned job.

## Request body

- ReplaceEmailUsernamesRequest
  - `replacements` object[], required
    - `user_id` string, required: email_users document id
    - `new_username` string, required: New local part (same domain), lowercase letters/digits/._-
  - `acknowledge_data_loss` boolean, required: Must be true — confirms the old mailboxes and ALL their messages are permanently deleted.

## Response `202`

Replacement queued

- ReplaceEmailUsernamesResponse
  - `data` object
    - `job_id` string
    - `status` string
    - `pairs_count` integer
    - `domains` object: Pairs queued per domain
    - `message` string
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `400`: Validation error
- `401`: Authentication required or token invalid
- `404`: Resource not found

---

[API](https://skmtc.dev/winnr/apis/winnr-api.md) · [All operations](https://skmtc.dev/winnr/apis/winnr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winnr/apis/winnr-api/revisions/a4f960beb1eb?raw)