---
title: "Create a test address"
method: POST
path: "/v1/addresses"
---

# Create a test address

`POST /v1/addresses`

## Request

- Base URL: `https://api.proxymail.qa`
- URL: `https://api.proxymail.qa/v1/addresses`
- Auth: HTTP bearer

## Headers

- `Proxy-Mail-QA-Run` string, uuid
- `Proxy-Mail-QA-Test` string

## Request body

- object
  - `label` string: What it is for, e.g. "Checkout test".
  - `name` string: A custom name before the @: 3–64 lowercase letters, digits, dots (not first, last or doubled) or any of ! # $ % & ' * - / = ? ^ _ ` { | } ~. Random when left out.
  - `persona` boolean: Also generate a fictional first name, last name and username.
  - `password` boolean: Also generate a strong password for the sign-up form and save it on the address. It is returned once, in this response; reading it again needs a key with "Can read saved passwords".
  - `lifetime_days` integer: Defaults to the plan's maximum.
  - `domain` string: One of the project's mail domains (GET /v1/project). Defaults to the project's.
  - `age` 'adult' | 'over21' | 'under18' | 'under15' | 'under13' | 'any' | 'turns18tomorrow' | 'turned18today': Give the persona a date of birth for this age: adult (18 to 65), over21, under18 (15 to 17), under15 (13 or 14), under13 (8 to 12), any (8 to 80), or someone who turns 18 tomorrow or turned 18 today. Leave out for no date of birth.
  - `date_of_birth` string, date: A date of birth to use instead of age, YYYY-MM-DD.
  - `country` string: Where the persona lives, as an ISO 3166-1 alpha-2 code such as GB or US (persona.country). Leave out for none.
  - `site` string: Where the account is used: the host or a page URL of the app under test, kept as the host.
  - `environment` string: Which environment of the app, such as staging, qa or local.

## Response `201`

The new address. With password: true, it also has `password`, shown this once.

- Address
  - `address` string
  - `label` string, nullable
  - `created_at` string, date-time
  - `expires_at` string, date-time
  - `persona` object, nullable
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `username` string, nullable
    - `date_of_birth` string, date: Present only when the address has one.
    - `country` string: ISO 3166-1 alpha-2 code, such as GB. Present only when the address has one.
  - `notes` string, nullable
  - `tags` string[]
  - `has_password` boolean
  - `password` string: Only in the response to creating it with password: true.
  - `site` string: Where it is used: the host of the app under test. Present only when set.
  - `environment` string: Which environment it is used in, such as staging. Present only when set.
  - `email_count` integer
  - `latest` object, nullable: The newest code or link, like Match.
  - `checked_out_until` string, date-time: Only while someone has it checked out of the pool.

## Other responses

- `400`: An error
- `401`: An error
- `402`: An error
- `429`: An error

---

[API](https://skmtc.dev/proxymail/apis/proxy-mail-qa-api.md) · [All operations](https://skmtc.dev/proxymail/apis/proxy-mail-qa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proxymail/apis/proxy-mail-qa-api/revisions/8f8a5e84cf5c?raw)