# HTTP

The HTTP API mirrors MCP one to one. The document at [/openapi.json](/openapi.json) is generated from the same operation registry as the MCP tools.

## Authentication

`Authorization: Bearer <key>` on every `/v1` request. `POST /sandbox` needs no auth.

Keys carry scopes: `read`, `propose`, `approve`, `configure`, `run`. Sandbox keys have all five. Each operation names the scope it needs.

## Requests

- `GET` operations take inputs as query parameters. `POST`/`PUT`/`DELETE` take a JSON body; path parameters come from the URL.
- `POST /v1/messages/ingest` also accepts a raw body with `Content-Type: message/rfc822` (an `.eml`) or `text/html`, with optional `X-Mximp-From`, `X-Mximp-To`, `X-Mximp-Subject` headers for html.
- Lists return newest first. Page with `before=<last id>` (ids are ULIDs and sort by creation time). Events page forward with `after=<id>`.

## Responses

JSON. Errors are `{"error": "<message>", "code": "<code>", "details"?: ...}` with an HTTP status: 400 bad input, 401 no or bad key, 403 missing scope, 404 not found, 409 conflict, 413 too large, 422 unparseable, 429 cap reached. Error messages name the operation that would help.

## Example

```bash
curl -s https://api.emailimport.com/v1/buckets/support-requests -H "authorization: Bearer $MXIMP_KEY"
```