Setup Email Client

Serverless Inbox is a JMAP mail server. To read and send mail from a desktop or mobile app, you need a client that speaks JMAP and signs in with OAuth.

---

Before you start

You need two things:

• Your JMAP hostname — the domain serving your mailbox’s API, referred to below as <jmap-host>. Your administrator provides this; it is the same host in every URL on this page.
• Your sign-in credentials — the same ones you use for webmail. You will enter them on the identity provider’s sign-in page, not into the mail client.

Note

You do not need a client ID or client secret. If your deployment has dynamic client registration enabled, the client obtains its own credentials automatically. If it is disabled, your administrator will give you a client ID to enter — ask them rather than guessing.

---

Check your client is compatible first

This is the step worth doing before anything else, because it decides whether setup can work at all.

JMAP client support for OAuth discovery and self-registration is still uneven. Some clients implement neither and expect a client ID typed in by hand; some implement discovery but not registration; some hardcode API paths in a way that cannot work against a standards-compliant server.

We deliberately do not publish a list of clients that work — such a list goes out of date quickly and would be wrong for some deployments. Instead, check your client against these two questions:

1. Does it discover the OAuth endpoints? A compatible client asks for a JMAP server hostname and finds the rest itself. A client that asks you to paste an authorization URL, a token URL, and a client ID is not doing discovery — it can still work, but you will need those values from your administrator.
2. Does it follow the session object? After signing in, a JMAP client must read the apiUrl field from the server’s session response and send its API requests there (RFC 8620 §3.1).

Caution

A client that hardcodes API paths instead of following apiUrl will not work, no matter how correctly the server is configured. If a client fails immediately after a successful sign-in, this is the most likely cause — and it is a limitation of the client, not something your administrator can fix.

---

Connect

The exact wording differs between clients, but a compatible client follows this sequence.

1. Add an account and choose JMAP as the account type.

2. Enter your JMAP hostname, <jmap-host>. Some clients ask for the full discovery URL instead — that is https://<jmap-host>/.well-known/jmap.

3. Let the client discover the server. It fetches the server’s configuration and, if needed, registers itself to obtain its own credentials. This happens without prompting you and typically takes a moment.

4. Sign in. The client opens a browser window on the identity provider’s sign-in page. Enter your credentials there. This is the expected behaviour — a JMAP client using OAuth should never ask for your password in its own interface.

5. Approve access if you are asked to, and the browser hands control back to the client.

6. Wait for the first sync. The client fetches your mailboxes and recent messages. Initial sync on a large mailbox can take a while.

Your credentials are never given to the mail client. It receives a token from the identity provider, which your administrator can revoke without changing your password.

---

If setup fails

What you see	What it usually means
The client cannot find the server	The hostname is wrong, or <jmap-host> is not reachable from your network. Confirm the hostname with your administrator.
A parse or “invalid response” error during setup	Discovery reached something that is not the JMAP server — often a misconfigured proxy or CDN in front of the domain. Report this to your administrator and point them at Configure Authentication.
The client asks for a client ID	Either the client does not support self-registration, or registration is disabled on your deployment. Ask your administrator for a client ID.
Registration is refused	Your deployment limits how many new client registrations happen per day. Wait and try again, or ask your administrator.
Sign-in succeeds, then the client fails	Most often the client is not following apiUrl from the session object — a client-side limitation. Try a different client.

When reporting a problem, include the client name and version, and what the client was doing when it failed (discovering, registering, signing in, or syncing). Those four stages fail for very different reasons.

---

Related

• OAuth Discovery & Dynamic Client Registration — what happens behind the scenes when a client connects
• Configure Authentication — the administrator’s side
• Use Webmail — reading mail without a separate client