When something is not working

The usual causes, listed by symptom rather than by error code.

Most of what goes wrong is one of a handful of things. This page is arranged by what you are seeing. If you already have an error code in front of you, /docs/errors lists every one of them by name, with what to do about it.

Nothing sends, and the reason is sending_locked_verify_email

The email address on the account has never been verified, and nothing goes out until it is. Verify it from the dashboard. This catches almost everyone once.

The assistant says it has no email tools

The tool list is read when the connection is made, so adding the server is not enough on its own: restart the assistant, or its gateway. On OpenClaw, openclaw mcp doctor mcpmailer --probe connects and prints what it actually found.

It connects, then gives up part-way through a wait

wait_for_reply can block for up to 300 seconds and some clients time out well before that. Raise the request timeout on the client. On OpenClaw that setting is requestTimeoutMs, in milliseconds, and it documents no default, so an unset one has no reason to clear the wait.

The agent receives nothing at all

Check the filter mode on the agent page. In whitelist mode everything from a sender you have not allowed is dropped before it is stored, so there is nothing to find afterwards. Subscribing to message.filtered is the only way to watch what is being turned away.

A reply shows up as a new conversation

Something composed a fresh message instead of answering. reply_all keeps the threading headers, which is what holds an exchange together in the recipient's mail client, and send_email threads too when you pass reply_to_message_id. It is also the difference between a reply and a cold send.

A custom domain will not verify

Records take up to an hour to spread, and the three DKIM records are issued a few minutes after you add the domain, so they show up on the second check rather than the first. domains:list prints exactly which records are still missing.

A send comes back recipient_suppressed

That address bounced or reported one of your messages as spam, so we refuse to write to it again. Take it off the list. Continuing to send to it is what gets a domain blocked.

Mail from the agent lands in spam

Send from a subdomain you verified rather than a root domain whose reputation is shared with everything else you send. Keep cold sends few and varied, since identical bodies to many recipients trip a guard here before they trip one at the receiver. /tools/mail-tester scores a real message and says what it would fix.

The webhook endpoint has stopped firing

First check that it was ever subscribed to the event: a new endpoint gets message.received and nothing else. Then read the delivery log, which records what each attempt got back. Twenty consecutive failures turn an endpoint off and email the workspace owner.

The webhook arrives but the signature will not verify

Almost always the body was parsed and re-serialised before the check. The signature covers the exact bytes we sent, so verify the raw text. During a secret rotation the header carries one signature per valid secret, so check every v1 in it rather than the first.

The same event arrives twice

That is by design: delivery is at-least-once, and a receiver that takes longer than ten seconds is retried even though it usually finished the work. Every copy carries the same id, so record the ids you have handled and return 200 for a repeat.

Everything comes back 429

Three hundred requests a minute per key, shared between the REST API and MCP. The response says how many seconds to wait. A loop polling for new mail is the usual cause, and /docs/waking is how to stop needing one.

If none of these is it, the delivery log, the agent page, and the activity log each record what actually happened rather than what was supposed to, and between them they cover most of the rest.