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

# Introduction

Use the Inbox Zero API to read inbox statistics, manage automation rules, and unsubscribe from senders programmatically.

If you prefer a CLI wrapper for scripts or bots, see the [API CLI](/api-reference/cli). To connect Cursor or Claude Code to your mailbox with OAuth, see the [MCP server](/api-reference/mcp).

## Supported Email Providers

Inbox Zero supports integration with:

* **Gmail** (Google Workspace and personal accounts)
* **Outlook** (Microsoft 365 and personal accounts)

## Getting Started

To begin using the Inbox Zero API, you'll need to obtain an API key. Here's how:

1. Log in to your Inbox Zero account
2. Navigate to the [Settings](https://www.getinboxzero.com/settings) page and scroll down to the `API Keys` section
3. Click on the `Create New Secret Key` button
4. Select the permissions (scopes) you need for your key
5. Choose an expiry period

<img src="https://mintcdn.com/inboxzero/wF-r9j9cfWEkqcpp/images/settings-api-key.png?fit=max&auto=format&n=wF-r9j9cfWEkqcpp&q=85&s=0dda1420ab2fe2221e45698a8e393ccb" alt="Create New Secret Key" width="2686" height="624" data-path="images/settings-api-key.png" />

API keys are scoped to a specific inbox account and only grant access to the permissions you select. Keep your key secure and do not share it publicly.

### Permissions

| Scope | Endpoints |
| - | - |
| `STATS_READ` | `GET /stats/by-period`, `GET /stats/response-time` |
| `RULES_READ` | `GET /rules`, `GET /rules/{id}` |
| `RULES_WRITE` | `POST /rules`, `PUT /rules/{id}`, `DELETE /rules/{id}` |
| `SENDERS_UNSUBSCRIBE` | `POST /senders/unsubscribe` |

A key may include more than one scope. Keys are also bound to one inbox account; they cannot read or change another inbox.

### Self-Hosting

If you are self-hosting Inbox Zero, set `NEXT_PUBLIC_EXTERNAL_API_ENABLED=true` and `API_KEY_SALT` before rebuilding the app. Generate the salt with `openssl rand -hex 32`. Use your deployment URL as the base URL for requests (for example, `https://your-domain.com/api/v1`).

## Base URL

All API requests should be made to the following base URL:

```
https://www.getinboxzero.com/api/v1
```

## Authentication

Include your API key in the header of each request:

```
API-Key: YOUR_API_KEY
```

For example, list rules:

```bash theme={null}
curl "https://www.getinboxzero.com/api/v1/rules" \
  -H "API-Key: YOUR_API_KEY"
```

Unsubscribe from a sender, using the same `API-Key` header as above:

```bash theme={null}
curl -X POST "https://www.getinboxzero.com/api/v1/senders/unsubscribe" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "senderEmail": "news@example.com" }'
```

To create a rule:

```bash theme={null}
curl -X POST "https://www.getinboxzero.com/api/v1/rules" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Archive newsletters",
    "runOnThreads": true,
    "condition": {
      "aiInstructions": "Newsletters and recurring promotional emails"
    },
    "actions": [{ "type": "ARCHIVE" }]
  }'
```

### Errors

API errors are returned as structured JSON:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key",
    "hint": "Include a valid API-Key header. See https://docs.getinboxzero.com/api-reference/introduction."
  }
}
```

| Status | Code | Meaning |
| - | - | - |
| `400` | `BAD_REQUEST` | Invalid query, path, or request body; an action may also be disabled by the deployment's feature flags |
| `401` | `UNAUTHORIZED` | The `API-Key` header is missing, invalid, or expired |
| `403` | `FORBIDDEN` | The key lacks a required scope or is not account-scoped |
| `404` | `NOT_FOUND` | The requested route or rule does not exist |
| `405` | `METHOD_NOT_ALLOWED` | The route exists, but does not support the requested HTTP method |
| `429` | `RATE_LIMITED` | Rate limited by the API or email provider |
| `500` | `INTERNAL_ERROR` | An unexpected server error occurred |

The OpenAPI schema is published at [https://www.getinboxzero.com/openapi.json](https://www.getinboxzero.com/openapi.json) (also `/api/v1/openapi` and `/.well-known/openapi.json`).

The `DELETE` rule action, which moves matching emails to trash, is available only when the deployment enables `NEXT_PUBLIC_DELETE_EMAIL_ACTION_ENABLED`. This feature flag is separate from `DELETE /rules/{id}`, which deletes a rule definition.

## Request New Endpoint

If you have a new endpoint that you would like to add to the API, open an issue on [GitHub](https://github.com/elie222/inbox-zero/issues/new).


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