The mailbox of an email source

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": "[email protected]", "secret": "<password>"}'

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": "[email protected]", "secret": "<password>"}'

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 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.

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": "[email protected]", "secret": "<password>"}'

Last modified on October 31, 2026

Overview

Authentication

Intake

Query

APM

RUM

Streams

Alerting

Correlation & Web

Platform & Administration

The mailbox of an email source