---
title: "Update domain alias"
method: PUT
path: "/v1/domains/{domain_id}/aliases/{alias_id}"
tags: ["Aliases"]
---

# Update domain alias

`PUT /v1/domains/{domain_id}/aliases/{alias_id}`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/domains/{domain_id}/aliases/{alias_id}`
- Auth: HTTP basic

Update a specific alias for a domain. Note: this endpoint does not accept `password` or `new_password` fields. To set or change alias credentials, use the "POST /v1/domains/:domain_id/aliases/:alias_id/generate-password" endpoint.

## Request body

- AliasUpdateInput
  - `name` string: Alias name
  - `recipients` union: If omitted, existing recipients are preserved. Pass an empty array to clear all forwarding recipients.
    - string: Line-break/space/comma separated string of valid email addresses, FQDNs, IPs, or webhook URLs
    - string[]: Array of valid recipients. Pass an empty array to remove all forwarding recipients (e.g. for IMAP-only aliases).
  - `description` string: Alias description
  - `labels` union
    - string: Line-break/space/comma separated string of labels
    - string[]: Array of labels
  - `has_recipient_verification` boolean: Require recipients to click verification link (defaults to domain setting)
  - `is_enabled` boolean: Enable or disable alias
  - `error_code_if_disabled` 250 | 421 | 550: Error code to use if alias is disabled (defaults to 250)
  - `has_imap` boolean: Enable or disable IMAP storage
  - `has_pgp` boolean: Enable or disable OpenPGP encryption
  - `public_key` string: OpenPGP public key in ASCII Armor format
  - `has_smime` boolean: Enable or disable S/MIME encryption
  - `smime_certificate` string: S/MIME X.509 certificate in PEM format
  - `has_wkd_disabled` boolean: Whether WKD (Web Key Directory) public key lookup is disabled for this alias
  - `max_quota` string: Storage maximum quota (e.g., '1 GB')
  - `vacation_responder_is_enabled` boolean: Enable or disable vacation responder
  - `vacation_responder_start_date` string: Vacation responder start date (e.g. YYYY-MM-DD)
  - `vacation_responder_end_date` string: Vacation responder end date (e.g. YYYY-MM-DD)
  - `vacation_responder_subject` string: Plaintext subject of vacation responder
  - `vacation_responder_message` string: Plaintext message of vacation responder
  - `retention` integer: Retention period in days (0-365) for Trash and Junk mailbox cleanup. Set to 0 to use automatic storage-based scaling.
  - `smtp_limit` integer: Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit.

## Response `200`

Domain alias updated successfully

- Alias
  - `user` object, required
    - `email` string, email, required
    - `display_name` string, required
    - `id` string, required
  - `domain` object, required
    - `name` string, required
    - `id` string, required
  - `name` string, required
  - `labels` string[], required
  - `is_enabled` boolean, required
  - `has_recipient_verification` boolean, required
  - `verified_recipients` string[], required
  - `pending_recipients` string[], required
  - `recipients` string[], required
  - `id` string, required
  - `object` 'alias', required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `storage_location` string, required
  - `has_imap` boolean, required
  - `retention` integer, required: Retention period in days (0-365) for Trash and Junk mailbox cleanup. 0 means automatic storage-based scaling.
  - `smtp_limit` integer: Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit.
  - `is_smtp_suspended` boolean: Whether this alias is currently suspended from outbound SMTP access.
  - `smtp_suspended_sent_at` string, date-time, nullable: The date and time when the alias was suspended from outbound SMTP.

## Other responses

- `400`: Error response
- `401`: Error response
- `403`: Error response
- `404`: Error response

---

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