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

# Mailbox operations and usage

> Work with sender identities, send submissions, quotas, and mailbox usage.

The Qubrics Mailbox API is for mailbox-scoped access. Use it when a client should act as a mailbox, or as one mailbox from a connected-app mailbox set, without managing team-wide resources.

## Operational resources

Operational endpoints expose what an agent needs to send safely and monitor
mailbox health without adding mutation authority.

### Sender identities

Use `GET /mailbox/identity` to read the mailbox's default sender name and
signatures. Use `PATCH /mailbox/identity` to update `name`,
`text_signature`, and `html_signature`.
Mailbox API sends use this sender name by default and append the matching
plain text or HTML signature when the send body includes that format.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/identity" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

```bash theme={null}
curl -X PATCH "https://app.qubrics.com/api/v1/mailbox/identity" \
  -H "Authorization: Bearer smx_mbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "text_signature": "Regards",
    "html_signature": "<p>Regards</p>"
  }'
```

`GET /mailbox/identities` lists all sender identities available to the
authenticated mailbox.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/identities" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

```json theme={null}
{
  "ok": true,
  "data": [
    {
      "id": "id_123",
      "name": "Support",
      "email": "support@example.com",
      "reply_to": [],
      "bcc": [],
      "text_signature": "Regards",
      "html_signature": "<p>Regards</p>",
      "may_delete": false
    }
  ],
  "pagination": {
    "has_more": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx",
    "identity_state": "identity_state_token"
  }
}
```

### Send submissions

Use submissions to inspect queued, sent, failed, or cancelled send lifecycle
records separately from the `messages/send` request that created them.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/submissions?email_ids=msg_123&limit=10" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

Useful filters:

| Parameter | Purpose |
| - | - |
| `identity_ids` | Comma-separated identity IDs. |
| `email_ids` | Comma-separated message IDs. |
| `thread_ids` | Comma-separated thread IDs. |
| `undo_status` | Match a specific submission undo state. |
| `after` | Match submissions sent at or after this time. |
| `before` | Match submissions sent before this time. |
| `cursor` | Continue from a previous page. |
| `limit` | Return `1` to `100` submissions. |
| `sort_by` | Sort by `send_at`, `email_id`, or `thread_id`. |
| `sort_direction` | Sort `asc` or `desc`. |

Read one submission with `GET /mailbox/submissions/{submission_id}`. Poll
`GET /mailbox/submissions/changes?since_state=...` to sync submission object
changes.

### Quotas and usage

Use quotas for detailed limits and `usage` for a compact health view.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/usage" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "resources": [
      {
        "quota_id": "quota_123",
        "name": "Mailbox storage",
        "resource_type": "octets",
        "scope": "account",
        "types": ["Mail"],
        "used": 536870912,
        "hard_limit": 1073741824,
        "warn_limit": 858993459,
        "soft_limit": null,
        "percent_used": 50,
        "limit_status": "ok"
      }
    ],
    "states": {
      "quota_state": "quota_state_token"
    }
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

Quota filters:

| Parameter | Purpose |
| - | - |
| `name` | Match quota name text. |
| `scope` | Match `account`, `domain`, or `global`. |
| `resource_type` | Match `count` or `octets`. |
| `type` | Match a resource family, such as `Mail`. |
| `cursor` | Continue from a previous page. |
| `limit` | Return `1` to `100` quotas. |
| `sort_by` | Sort by `name` or `used`. |
| `sort_direction` | Sort `asc` or `desc`. |

Poll `GET /mailbox/quotas/changes?since_state=...` to sync quota changes.

## Next steps

> [card] [Calendars and events](https://sendmux.ai/docs/developer-tools/mailbox-api/calendars.md)

> [card] [Threads](https://sendmux.ai/docs/developer-tools/mailbox-api/threads.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.