# Create a view

Source: https://docs.maylee.app/api-reference/views/create-view

`POST https://api.maylee.app/api/v1/views`

Scope: `write`.

Saves a filter tree under a name. The tree is bounded like `?filters=`: 5 levels, 50 conditions, 500-character values.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | A unique value per operation, such as a UUID. Replays the stored response for 24h. Reusing a key with a different body returns 409. 0 to 255 characters. |

## Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 1 to 100 characters. |
| `filters` | object or object or object | no | Filter tree in the public DSL, or `{}` for no filter. |
| `icon` | string or null | no | An emoji. No markup. 0 to 32 characters. |

## Example request

```bash
curl -X POST "https://api.maylee.app/api/v1/views" \
  -H "Authorization: Bearer $MAYLEE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": {
    "_and": [
      {
        "id": "c1",
        "label": "ai_label",
        "type": "contains",
        "value": "cmtgai1b2c3d4e5f6g7h8i9j"
      },
      {
        "id": "c2",
        "label": "read_status",
        "type": "is_false",
        "value": ""
      }
    ],
    "id": "g1"
  },
  "icon": "🎯",
  "name": "Leads to answer"
}'
```

## Responses

### 201

Created.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `view` | View | yes |  |
| `view.createdAt` | string (date-time) | yes |  |
| `view.filters` | object or object or object | yes | Filter tree in the public DSL, or `{}` for no filter. |
| `view.icon` | string or null | yes |  |
| `view.id` | string | yes |  |
| `view.mailboxIds` | array of string | yes | Mailboxes the view is restricted to. Empty means all. |
| `view.name` | string | yes |  |

```json
{
  "view": {
    "createdAt": "2026-07-01T10:00:00.000Z",
    "filters": {
      "_and": [
        {
          "id": "c1",
          "label": "ai_label",
          "type": "contains",
          "value": "cmtgai1b2c3d4e5f6g7h8i9j"
        },
        {
          "id": "c2",
          "label": "read_status",
          "type": "is_false",
          "value": ""
        }
      ],
      "id": "g1"
    },
    "icon": "🎯",
    "id": "cmvw1a2b3c4d5e6f7g8h9i0j",
    "mailboxIds": [],
    "name": "Leads to answer"
  }
}
```

### 400

Invalid payload, invalid filter tree, or a bound was exceeded.

### 401

Missing, malformed, revoked or expired API key.

### 403

Key lacks the required scope, or outbound sending is not enabled on it.

### 429

Per-minute rate limit (`RATE_LIMIT_EXCEEDED`) or monthly quota (`QUOTA_EXCEEDED`) exhausted.

Errors use the format `{ "code", "error", "details" }`: see [Errors](/errors.md).