---
title: "Create an alias"
method: POST
path: "/aliases"
tags: ["Aliases"]
---

# Create an alias

`POST /aliases`

## Request

- Base URL: `https://faivelo.com/api/v1`
- URL: `https://faivelo.com/api/v1/aliases`
- Auth: HTTP bearer

Creates a forwarding alias that delivers to one or more destination addresses. The domain must be DNS-verified — mail cannot route to an alias on an unverified domain, so creation is rejected with a 403. Requires scope `aliases:write`.

## Request body

- CreateAliasRequest: Request body for creating an alias
  - `domain` string, required
  - `localPart` string: The part before the @. 1–64 chars, alphanumeric plus `._%+-`. Required unless `catchAll` is true.
  - `catchAll` boolean: Create the domain catch-all (`*@domain`): forwards mail sent to any address that has no mailbox or alias of its own. One per domain.
  - `destinations` string[], required: One or more email addresses to forward to (max 20)

## Response `200`

Alias created

- object
  - `success` boolean
  - `data` Alias: Email alias (forwarding address)
    - `address` string
    - `localPart` string
    - `destinations` string[]
    - `active` boolean
    - `createdAt` string, date-time

## Other responses

- `401`: Missing or invalid API key
- `402`: The account's plan does not include the API (`plan_required`)
- `403`: The key lacks the required scope
- `409`: Alias already exists
- `429`: Rate limit exceeded

---

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