Mail providers
MailProvider/list — the curated IMAP provider presets for prefilling mailbox creation.
A curated catalog of known IMAP providers and their server coordinates. Use it to build an "add a mailbox" UX — prefill the host, port and security when the user picks a provider — before completing a classical account connection.
The presets carry nothing sensitive, so any valid access token may read them — no scope is required.
The preset catalog is served over JSON-RPC as MailProvider/list.
Any valid access token may read it.
MailProvider/list
POST /rpc
Content-Type: application/json
Authorization: Bearer <access_token>
{
"jsonrpc": "2.0",
"id": 1,
"method": "MailProvider/list",
"params": {}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"providers": [
{
"id": "fastmail",
"display_name": "Fastmail",
"imap_host": "imap.fastmail.com",
"endpoints": [
{ "port": 993, "security": "TRANSPORT_SECURITY_TLS" },
{ "port": 143, "security": "TRANSPORT_SECURITY_STARTTLS" }
]
},
{
"id": "gmail",
"display_name": "Gmail",
"imap_host": "imap.gmail.com",
"endpoints": [{ "port": 993, "security": "TRANSPORT_SECURITY_TLS" }]
}
]
}
}The MailProvider object
| Field | Type | Notes |
|---|---|---|
id | string | Stable key, e.g. gmail |
display_name | string | Human label; the list is sorted alphabetically by this |
imap_host | string | IMAP server hostname |
endpoints | ImapEndpoint[] | Every { port, security } the provider accepts, TLS first (the default to pre-select) |
Each ImapEndpoint is a { port, security } pair, where security is a
TransportSecurity value (TRANSPORT_SECURITY_TLS,
TRANSPORT_SECURITY_STARTTLS, or TRANSPORT_SECURITY_PLAINTEXT). After
AccountConnections/prepare and AccountConnections/start
(Create or attach service bindings), map the
user's chosen provider and endpoint into the endpoint of an
AccountConnections/complete_classical request:
{
"connection_id": "connection_01H9Z…",
"authorization_input_id": "mail-auth",
"endpoint": {
"host": "imap.fastmail.com",
"port": 993,
"username": "me@fastmail.com",
"password": "<app-password>",
"security": "TRANSPORT_SECURITY_TLS"
}
}The preset carries IMAP coordinates only. When MAIL_SEND was selected,
supply explicit smtp_endpoint coordinates as well; Gateway never derives an
SMTP hostname from the IMAP hostname.
Conversations and labels per provider
| Provider | Conversation (thread_id on email.received) | Labels (Labels/list) |
|---|---|---|
| Gmail | threadId | Gmail labels, created in the catalogue; a system label's name is refused with label_name_unsupported, a name another label has with label_name_taken |
| Outlook (Graph) | conversationId | Outlook categories, created in the master list; without mailbox-settings access (creation: on_apply) created when first applied; a name with a comma (on the master list also a semicolon, or over 255 characters) is refused with label_name_unsupported, a name another category has in any case with label_name_taken |
| IMAP | none: group by References, In-Reply-To and subject yourself | Keywords spelled as Thunderbird tag keys, created when first applied; a reserved keyword name is refused with label_name_unsupported |
LabelSupport on Labels/list says what an account allows, so a client never
needs to switch on the provider.
A reply you send or save as a draft joins its parent's conversation on every
provider when it carries In-Reply-To (and References) and keeps the
parent's subject; a reply prefix such as Re: does not count as a change.
Gmail's API threads only messages that name their thread, so Gateway finds
the parent's thread for you. A reply with a new subject starts a new
conversation, as in Gmail and Outlook.