# Connections (https://docs.getbeel.com/en/api/connections)

Connect mailboxes and Stripe, scan for supplier invoices and review the documents collected.

Getbeel collects supplier invoices from email (Gmail, Outlook, IMAP or a forwarding address) and turns Stripe invoices into fatture. The API exposes the same connections as **Settings → Email** and the fatture emesse page.

Scopes: `connections:read` to read, `connections:write` to connect, scan and sync; `received_invoices:write` to approve collected documents. Reading works with any key; changes need a live key (`403 livemode_required` otherwise). Each document read with AI is paid from the prepaid balance (`402 insufficient_balance` when it does not cover it).

## List connections [#list-connections]

```bash
curl https://www.getbeel.com/api/v1/connections \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Each connection has `provider` (`gmail`, `outlook`, `imap`, `forwarding`, `stripe`), `active` and `health.status`: `healthy`, `reconnect_required` (connect it again), `error` or `unknown`.

## Connect a mailbox [#connect-a-mailbox]

Gmail and Outlook use OAuth, which a person has to approve. The API returns a link:

```bash
curl -X POST https://www.getbeel.com/api/v1/connections/email \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "gmail" }'
```

Open `url` in a browser signed in to Getbeel as a member of the team (it asks you to sign in otherwise), approve access, and you land back in the app. The mailbox then appears in `GET /connections`.

IMAP connects directly: Getbeel tests the login (port 993, TLS) and saves the password encrypted. Use an app password.

```bash
curl -X POST https://www.getbeel.com/api/v1/connections/email \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "imap", "email": "fatture@example.it", "password": "app-password", "host": "imap.example.it" }'
```

New mailboxes count toward the plan's mailbox limit (`402` when it is reached).

## Scan a mailbox [#scan-a-mailbox]

```bash
curl -X POST https://www.getbeel.com/api/v1/connections/$CONNECTION_ID/scan \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-10-01", "to": "2026-10-31" }'
```

At most a year per request. The scan runs in the background (`202`); every invoice found fires `received_invoice.created` and appears in `GET /received-invoices?source=email`.

## Forwarding address [#forwarding-address]

`GET /forwarding-address` returns the address to forward supplier invoices to, or `null` until it is set up in the app (it needs the email routing add-on). Forwarded invoices have `source: forwarded`.

## Review collected documents [#review-collected-documents]

Collected documents are the [received invoices](/en/api/reference) with a `source` (`email`, `forwarded`, `manual`, `bank_transaction`). The ones waiting for a person have `status: pending_review`:

```bash
curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

`approve` sets `verified`, `reject` sets `rejected`. Documents still being read, missing-document placeholders and exported ones cannot be reviewed (`409`).

## Stripe [#stripe]

- `POST /connections/stripe` returns a link to Stripe Connect; after approving you land on the fatture emesse page.
- `POST /connections/stripe/sync` (optional `{ "from", "to" }`, default the last 30 days) imports Stripe invoices as fatture emesse. It needs the SDI add-on and quota; if the connection has automatic sending on, the invoices also go to SDI.

## With an AI assistant [#with-an-ai-assistant]

The [MCP server](/en/api/mcp) has `list_connections`, `connect_mailbox` (returns the link), `scan_mailbox`, `list_collected_documents` and `approve_collected_document`. IMAP passwords never go through the assistant: connect IMAP in the app or with the API.
