---
title: "Add an alias address"
method: POST
path: "/v1/mailboxes/{mailbox_id}/email/aliases"
tags: ["Email settings"]
---

# Add an alias address

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

## Request

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

Requires a paid plan and a full-account owner or administrator with mailbox-admin permission. The primary address stays unchanged. On a mailbox whose primary address is on your domain, the first revdokumail.com alias becomes its base address and uses no alias slot.

## Path parameters

- `mailbox_id` string, required

## Request body

- object
  - `username` string, required: Alias name before @. On revdokumail.com, a prefix with a 4-character random suffix; on a custom domain, the exact name.
  - `domain` string
  - `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 `202`

Accepted

- 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

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