---
title: "Change the primary address"
method: POST
path: "/v1/mailboxes/{mailbox_id}/email/rotate"
tags: ["Email settings"]
---

# Change the primary address

`POST /v1/mailboxes/{mailbox_id}/email/rotate`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/mailboxes/{mailbox_id}/email/rotate`
- Auth: HTTP bearer

Requires mailbox admin permission and a paid plan, except for a change back to revdokumail.com. Send the current address as expected_address. Omit username for a generated name. A custom-domain change returns 202; read the settings until assignment.status is active or failed. For account owners and administrators the old address becomes an alias unless keep_old_as_alias is false. Without a free alias slot the request returns EMAIL_ALIAS_LIMIT; send false to retire the old address. A change from revdokumail.com to a customer domain always keeps the old address as the revdokumail.com base address, which uses no alias slot. A change from a customer domain back to revdokumail.com makes that base address the main address again at once (200, assignment.status active): username is ignored, no address change is counted and it works on every plan.

## Path parameters

- `mailbox_id` string, required

## Request body

- object
  - `confirm` true, required
  - `expected_address` string, required: Current address from your last settings read. A different current address returns EMAIL_ADDRESS_CHANGED.
  - `username` string: New name before @. On revdokumail.com, a prefix with a new 4-character random suffix; on a custom domain, the exact name.
  - `domain` string: Available platform domain, a ready domain of this account, or platform.
  - `keep_old_as_alias` boolean: Keep the old address as an alias. Defaults to true for account owners and administrators while the old domain still receives email, otherwise false. Keeping it needs a free alias slot and an account owner or administrator. A change from revdokumail.com to a customer domain always keeps the old address as the base address. That needs no alias slot and no administrator.
  - `account_id` string: Select another granted account for this request.
  - `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.

## Response `200`

Success

- object
  - `success` true, required
  - `data` MailboxEmailSettings, required: Address settings of one mailbox.
    - `address` string: Primary address. Present when the credential has write access to the mailbox. Show it after the title.
    - `message_count` integer, nullable, required: Emails currently stored. Null while the email index is being prepared.
    - `unread_count` integer, nullable, required: Stored emails with shared unread status. Null while the email index is being prepared.
    - `last_received_at` string, date-time, nullable, required: Receipt time of the latest saved email; null before the first email.
    - `receiving_enabled` boolean, required: Whether the mailbox can receive email now.
    - `blocked_reason` string: Why receiving is unavailable. Omitted when receiving_enabled is true.
    - `sending_enabled` boolean, required: Whether the mailbox can send replies now.
    - `sending_blocked_reason` string: Why sending is unavailable. Omitted when sending_enabled is true.
    - `username` string, nullable: The part of address before @.
    - `aliases` EmailAlias[], required
      - `id` string, required
      - `address` string, required
      - `active` boolean, required: Within the current alias allowance. Mailbox receiving holds still apply.
    - `available_domains` object[]
      - `hostname` string
      - `kind` 'platform' | 'custom'
    - `assignment` object: No candidate address is disclosed. Keep using address until status is active; on pending poll the email endpoint.
      - `id` string
      - `status` 'pending' | 'active' | 'failed'
      - `hostname` string
      - `error` object
        - `code` string
        - `message` string
        - `retryable` boolean
    - `customization` object: Caller-specific customization capability on the dedicated email GET/rotate endpoints.
      - `allowed` boolean
      - `blocked_reason` string, nullable
      - `settings_url` string, nullable: Account-domain settings link for administrators; null otherwise.
    - `sender_allowlist` EmailSenderAllowlist
      - `enabled` boolean, required
      - `entries` string[], required
      - `version` string, required
      - `max_entries` integer, required
      - `editable` boolean, required

## Other responses

- `202`: Change pending
- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

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