---
title: "Create time limited alias"
method: POST
path: "/api/v1/add/time_limited_alias"
tags: ["Aliases"]
---

# Create time limited alias

`POST /api/v1/add/time_limited_alias`

You may create a time limited alias using this action. It takes a JSON object containing a domain and mailbox informations. Mailcow will generate a random alias.

## Request body

- object
  - `username` string — the mailbox an alias should be created for
  - `domain` string — the domain
  - `description` string — a description for the alias, defaults to an empty string
  - `validity` integer — how many hours the alias stays valid, 1 to 87600, defaults to 8760 (one year)
  - `permanent` boolean — keep the alias after it expired, defaults to false

## Response `200`

OK

- object
  - `log` unknown[] — contains request object
    - unknown
  - `msg` unknown[]
    - unknown
  - `type` 'success' | 'danger' | 'error'

## Other responses

- `401` — Unauthorized

## Changes

- **2026-07-17** `50e1d81e874c` — 3 warning
  - removed the request property `description`
  - removed the request property `permanent`
  - removed the request property `validity`
- **2026-07-14** `a51b72968d1e` — 3 info
  - added the new optional request property `description`
  - added the new optional request property `permanent`
  - added the new optional request property `validity`
- **2021-11-12** `161884929ef0` — 1 info
  - endpoint added
- **2020-06-07** `47523aca063a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/mailcow/apis/mailcow-api/changes/api/v1/add/time_limited_alias/post.md)

---

[API](https://skmtc.dev/mailcow/apis/mailcow-api.md) · [All operations](https://skmtc.dev/mailcow/apis/mailcow-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mailcow/mailcow-api/revisions/ae01d1d7886a/schema)