# Create an inbox (idempotent on requested username)

**`POST https://myagentmail.com/v1/inboxes`**

Group: Inboxes
Operation ID: `createInbox`

Requires tenant master or workspace master key.

## Username allocation
- If `username` is set and your tenant **already** has an inbox at
  `username@domain`, returns that inbox (HTTP **200**, body
  contains `existed: true`). The call is idempotent — safe to
  retry.
- Otherwise tries to create `username@domain`. If the global
  username is taken by another tenant, falls back to
  `username1`, `username2`, … through `username99`. The actual
  allocated username is in the response body.
- Pass `?strict=true` to disable auto-fallback. With strict mode,
  a global collision returns HTTP **409** with the conflicting
  resource info instead of suffixing.

IMAP/SMTP credentials — `apiKey` and `imapPassword` — are only
returned on first creation, never on idempotent returns.


## Query parameters

- `strict` (boolean) — When `true`, the request fails with `409 USERNAME_TAKEN` if
the requested `username@domain` is already taken by another
tenant. When omitted (default), we auto-fallback to
`username1`, `username2`, etc.

## Request body

Content-Type: `application/json`

```json
{
  "username": "string",
  "displayName": "string",
  "domain": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000"
}
```

## Responses

### 200 — Idempotent return — your tenant already has an inbox at the

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "email": "scout-abc123@delegated.cc",
  "canonicalEmail": "scout-abc123-10deac42@myagentmail.com",
  "username": "string",
  "domain": "string",
  "displayName": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000",
  "addresses": [
    {
      "address": "scout-abc123@delegated.cc",
      "isPrimary": false
    }
  ],
  "imapPassword": "string",
  "imap": {
    "host": "imap.myagentmail.com",
    "port": 993,
    "tls": false,
    "username": "string",
    "password": "string"
  },
  "smtp": {
    "host": "smtp.myagentmail.com",
    "port": 587,
    "starttls": false,
    "username": "string",
    "password": "string"
  },
  "createdAt": "2026-05-01T08:11:44.605Z"
}
```

### 201 — Newly created. `apiKey` and `imapPassword` are returned once — store them now.

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "email": "scout-abc123@delegated.cc",
  "canonicalEmail": "scout-abc123-10deac42@myagentmail.com",
  "username": "string",
  "domain": "string",
  "displayName": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000",
  "addresses": [
    {
      "address": "scout-abc123@delegated.cc",
      "isPrimary": false
    }
  ],
  "imapPassword": "string",
  "imap": {
    "host": "imap.myagentmail.com",
    "port": 993,
    "tls": false,
    "username": "string",
    "password": "string"
  },
  "smtp": {
    "host": "smtp.myagentmail.com",
    "port": 587,
    "starttls": false,
    "username": "string",
    "password": "string"
  },
  "createdAt": "2026-05-01T08:11:44.605Z"
}
```

### 403 — Plan limit reached

```json
{
  "error": "string",
  "code": "VALIDATION_ERROR"
}
```

### 409 — `USERNAME_TAKEN` — only returned when `?strict=true` is set

```json
{
  "error": "string",
  "code": "VALIDATION_ERROR"
}
```

## Code samples

### TypeScript

```typescript
import { MyAgentMail } from "myagentmail";

const client = new MyAgentMail({ apiKey: process.env.MYAGENTMAIL_API_KEY! });

// POST /v1/inboxes
const result = await client.request("post", "/v1/inboxes", { body: {
  "username": "string",
  "displayName": "string",
  "domain": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000"
} });
```

### curl

```bash
curl -X POST 'https://myagentmail.com/v1/inboxes' \
  -H 'X-API-Key: $MYAGENTMAIL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "string",
  "displayName": "string",
  "domain": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000"
}'
```

### Python

```python
import os, requests

r = requests.post(
    "https://myagentmail.com/v1/inboxes",
    headers={"X-API-Key": os.environ["MYAGENTMAIL_API_KEY"]},
    json={
        "username": "string",
        "displayName": "string",
        "domain": "string",
        "workspaceId": "00000000-0000-0000-0000-000000000000"
    },
)
r.raise_for_status()
print(r.json())
```