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

# The mailbox of an email source

> Set up the IMAP mailbox an email source reads, test it, and see how the last read went.

```http theme={null}
GET    /api/v1/alerts/sources/{id}/mailbox
PUT    /api/v1/alerts/sources/{id}/mailbox
DELETE /api/v1/alerts/sources/{id}/mailbox
POST   /api/v1/alerts/sources/{id}/mailbox/test
```

The IMAP mailbox an [email source](https://docs.molesignal.com/en-US/alerting/sources.md#email) reads. Reading takes `alerts.sources.read`; changing and testing take `alerts.sources.manage`. Only a source of kind `email` has one. It is set up on the source's receiving cluster and does not sync through federation. Before a `PUT`, write the sender list on the source (`email.allowed_senders`).

**Body of `PUT` and `test`**

| Field | Type | Description |
| - | - | - |
| `host` | string | Required: a host name, without a scheme or port. |
| `port` | integer | 993 by default. |
| `security` | string | `tls` (default), `starttls` or `none`. |
| `username` | string | Required. |
| `secret` | string | The password or client secret. Never returned; empty keeps it. |
| `auth` | object | `{"kind": "password"}` (default), or `{"kind": "oauth2", "token_url": "https://…", "client_id": "…", "scope": "…"}` for a token from client credentials over `XOAUTH2`. |
| `folder` | string | `INBOX` by default. |
| `poll_secs` | integer | How often it is read, 15 to 3600, 60 by default. |

Connections go only to where the host resolves at that moment, never to a cloud metadata address. A change of host, account or folder starts the position over from the next connection.

**Answer of `GET` and `PUT`** (`GET` gives `null` when none is set up)

| Field | Description |
| - | - |
| `settings` | The settings above without `secret`. |
| `secret_set` | Whether the secret is set. |
| `reading` | It has connected, and reads what arrives from then on. |
| `last_polled_at`, `last_success_at` | The last read and the last good one (microseconds). |
| `last_error` | Why the last read failed; cleared by a good one. |

`test` connects once with the settings in the body (an empty `secret` uses the stored one) and answers `{"ok": true, "messages": 3}`, or `503` with what the mail server said.

```bash cURL theme={null}
curl -X PUT "http://localhost:5080/api/v1/alerts/sources/$SOURCE_ID/mailbox" \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"host": "imap.example.com", "username": "alerts@example.com", "secret": "<password>"}'
```


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