---
title: "Create new domain alias"
method: POST
path: "/v1/domains/{domain_id}/aliases"
tags: ["Aliases"]
---

# Create new domain alias

`POST /v1/domains/{domain_id}/aliases`

## Request

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

Create a new alias for a specific 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

- AliasInput
  - `name` string: Alias name (if not provided or if blank, then a random alias is generated)
  - `recipients` union: List of recipients. If not provided or empty, defaults to the requester's email
    - string: Line-break/space/comma separated string of valid email addresses, FQDNs, IPs, or webhook URLs
    - string[]: Array of valid recipients
  - `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: Whether to enable or disable this alias
  - `error_code_if_disabled` 250 | 421 | 550: Error code if alias is disabled. Defaults to 250
  - `has_imap` boolean: Enable or disable IMAP storage for this alias
  - `has_pgp` boolean: Enable or disable OpenPGP encryption for this alias
  - `public_key` string: OpenPGP public key in ASCII Armor format
  - `has_smime` boolean: Enable or disable S/MIME encryption for this alias
  - `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 max quota (e.g. '1 GB')
  - `vacation_responder_is_enabled` boolean: Enable or disable vacation responder
  - `vacation_responder_start_date` string: Start date (e.g. 'YYYY-MM-DD') for vacation responder
  - `vacation_responder_end_date` string: End date (e.g. 'YYYY-MM-DD') for vacation responder
  - `vacation_responder_subject` string: Plaintext subject for vacation responder
  - `vacation_responder_message` string: Plaintext message for 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 created 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`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `429`: Too Many Requests

---

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