> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tempinbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Addresses

> Create and manage temporary email addresses.

<Note>
  `POST /api/new_address` requires Cloudflare Turnstile when enabled on the server. For automation, extract a JWT from the browser instead of calling this endpoint directly. See [Authentication](/api-reference/authentication) for details.
</Note>

***

## Create Address

`POST /api/new_address`

Creates a new temporary inbox. Returns a JWT and sets `jwt` + `session_id` cookies.

### Turnstile Requirement

This endpoint is protected by Cloudflare Turnstile on the public instance. Raw API calls without a valid `cf_token` will fail.

**For automation:** Use a JWT extracted from the browser UI instead. See [Authentication → API automation](/api-reference/authentication).

**For self-hosted instances** with Turnstile disabled:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-instance.com/api/new_address \
    -H "Content-Type: application/json" \
    -d '{}'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://your-instance.com/api/new_address', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({}),
  });
  const { address, jwt } = await res.json();
  ```

  ```python Python theme={null}
  import requests
  r = requests.post('https://your-instance.com/api/new_address', json={})
  address = r.json()['address']
  jwt = r.json()['jwt']
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "address": "swift-cloud-7x4@tempinbox.dev",
  "jwt": "eyJhbGciOiJIUzI1NiJ9..."
}
```

### Custom Name

To request a specific local part (before `@`):

```json theme={null}
{ "name": "mytest", "domain": "tempinbox.dev" }
```

<Warning>
  Custom names may be rejected if they are on a blocklist or the server has disabled custom names. Always handle errors and fall back to random generation.
</Warning>

***

## Get Address Info

`GET /api/settings`

Returns the address for the current JWT. Useful for verifying auth.

```bash theme={null}
curl "https://tempinbox.dev/api/settings" \
  -H "Authorization: Bearer <jwt>"
```

**Response**

```json theme={null}
{ "address": "swift-cloud-7x4@tempinbox.dev" }
```

***

## Delete Address

`DELETE /api/delete_address`

Permanently deletes the address and all its emails. Irreversible.

```bash theme={null}
curl -X DELETE "https://tempinbox.dev/api/delete_address" \
  -H "Authorization: Bearer <jwt>"
```

**Response**

```json theme={null}
{ "success": true }
```

**Rate limit:** Per IP. Avoid calling in tight loops.