Troubleshooting

What to do when a domain doesn't verify, mail doesn't arrive, doesn't leave or is refused, or an agent, a token or a webhook stops working. Each section starts from what you see, then gives the usual causes and the fix for each.

Administrators often hear about a problem first in Notices, which say what happened, what to do and who can fix it (Notices). A send's page in Activity explains what happened to one email (A send's page).

Domains and receiving

A domain doesn't verify

Open the domain from Addresses. Each DNS record shows Not found, OK or Mismatch, with what is published now, and Check again checks at once. Mailroomly also checks every 5 minutes on its own, so you can close the page (DNS records).

Cause	What to do
The DKIM record is not published. The domain stays Waiting for DNS: nothing is set up before Mailroomly sees it.	Publish the DKIM signature record first, with its type, name and value copied exactly.
Your DNS panel added your domain to the name a second time. The record shows Not found or Mismatch.	Enter only the part before your domain: `bounce`, not `bounce.yourcompany.com`.
The record is behind a proxy in your DNS panel.	Set every record to "DNS only": a proxied CNAME doesn't point where it should.
The name already has an SPF record. A name can have only one.	Add the `include:` part shown on the page to the existing record instead of adding a second one.
The Inbound mail (MX) record stays pending.	Replace the domain's other MX records with it, instead of adding it next to them.
The records were published a short while ago.	Wait. Most DNS panels publish within minutes, some take a few hours, and at worst up to 48 hours.
The domain shows Being verified, or Setup failed in one of the platform’s accounts.	Nothing to do for Being verified. For a failed setup, Mailroomly retries on its own: check that the DKIM record is still published, and contact us if it persists.
The domain shows Domain already verified by another organization.	Another organization proved it first. Contact us if the domain is yours.
Adding the domain is refused because too many domains are waiting.	At most 10 domains can wait for their DKIM record at once: publish their records, or delete the ones you don't use.
A domain that was verified shows Needs attention, or a record shows Changed.	A record changed or disappeared after verification. Put it back as the page shows it (DNS records changed).

While you wait, you can start on the free address, invite your team and connect your agents (The free address). With your organization's own sending account, a domain has three DKIM records instead of one (Your own sending accounts).

Your agent can check for you: "Check mail.yourcompany.com again and tell me which records are missing." It uses verify_domain and get_domain, with a token that has Manage domains (Administration scopes).

Email to an address doesn't arrive

Cause	What to do
The domain doesn't receive. Receiving needs a domain set to Sends and receives and the Inbound mail (MX) record OK.	Choose Sends and receives under What this domain does in the domain's Settings (confirm with Turn on receiving), then publish the inbound MX record (DNS records).
The domain's old MX records are still there. While another MX record remains, the domain's mail is split between two systems.	Remove the old MX records. For a day or two after the change, some senders still deliver to the old records until their copy expires.
The address doesn't exist on the domain, and the domain has no catch-all address. That mail doesn't reach anyone.	Create the address (New address), or choose a Catch-all address under the domain's Settings.
The address only sends. A Sends only address doesn't receive replies.	Change its Direction to Sends and receives in Details › Edit on the address's page.
Your previous email host forwards to Mailroomly, and the forwarding is off or not confirmed.	Check the forwarding at your previous host. Its confirmation email arrives in the address's inbox in Mailroomly (Moving an existing mailbox's mail).
Mailroomly support paused receiving for the address or its domain. The page says so, with how many emails were not received.	Write to us at hello@mailroomly.com. Email sent while receiving is paused is not kept and can't be recovered (Receiving paused by support).
The domain's page shows Receiving email is paused on the platform.	Mailroomly is fixing it. There is nothing to do on your side.
The domain receives through your organization's own sending account, and the notice Inbound email stopped is open.	Make the change the notice names in that account (Inbound email stopped).
The email arrived, but you can't see it. Members see only the addresses they were given.	Administrators find every email that arrived in Activity › Received, with the address it reached. A member asks an administrator for access to the address (Who can open an address).

Email that arrives and looks like spam is still shown, marked Suspected spam (Inbox).

Sending

Your email lands in spam

Each recipient's mail program decides where your email goes, and it weighs what your domain publishes and how people react to your email. Check these, in order:

Every record of the domain is OK. On the domain's page, under Technical details, the DKIM signature, MAIL FROM (MX), MAIL FROM (SPF) and DMARC policy records should show OK. Marketing email needs a DMARC record (DNS records).
People asked for your email. Send only to people who chose to receive it, never to bought or old lists. Recipients who mark your email as spam raise your complaint rate, and Mailroomly warns you in Notices (High complaint rate).
Each email has the right type. Keep newsletters as marketing and invoices or password resets as transactional, so complaints about one don't weigh on the other (Campaigns and marketing).
Newsletters can be left easily. Put a visible {{unsubscribe_url}} link in every marketing email: people who can't find one mark the email as spam instead. Send one message per recipient, with the batch endpoint.
Links look like your own. A Custom tracking domain tracks opens and clicks through your own domain, so your links don't share another sender's reputation (Addresses and domains).

Recipients bounce, or an address is blocked

Open the send in Activity: its page says what happened in plain words, and what to do (A send's page). Mailroomly blocks an address on its own when sending to it again would harm your sending. Activity › Blocked lists each one with its reason (Blocked addresses):

Reason	What to do
Hard bounce: the address doesn't exist. Blocked for every type of email.	Check the spelling with the person, and send to the right address.
Repeated soft bounces: the mailbox was full, or the server refused for now, 3 times in 7 days. Blocked for that type of email.	Reach the person another way, and unblock the address once it works again.
Complaint: the recipient marked an email as spam. Blocked for the type of email it came from.	Don't send that type of email to them again.
Refused by validation: the address looked unlikely to be delivered. It doesn't count as a bounce.	Find where such addresses come from, for example a sign-up form without confirmation.
Unsubscribed: the person left your marketing email.	Unblock only if they subscribe again.
Blocked by the platform (hard bounce): it bounced as non-existent for another organization on the platform, within 180 days.	You can't remove it. If the address works again, ask the platform team.
An erased address: you erased the person's data. It is blocked, but not listed.	If the person asks to hear from you again, use Allow an erased address again… in Activity › Blocked (Erasing a person's data).

To unblock an address, select Remove next to it in Activity › Blocked. Do it only when you know the address works and the person wants your email. An agent does it with remove_suppression, with a token that has Manage blocked addresses.

When many recipients bounce, clean the list before the next send: bounce rates of 2 % raise a notice, and higher rates pause that type of email (Sending health).

A send was refused

A refused send says why, in the inbox, on a send's page, or in the answer your app or agent gets. In the inbox, your text stays in the composer, so you can send it later.

The message says	Why	What to do
Your organization reached its daily sending limit. It resets at midnight UTC.	Your organization's daily cap, 1,000 recipients a day for a new account.	Wait for midnight UTC. Before a large launch, contact us (Daily limits).
You reached your daily limit of recipients. It resets at midnight UTC. If you need more, ask an administrator.	Your own daily limit. What your AI agents send for you counts towards it.	Wait for midnight UTC. If the limit is too low for your work, an administrator asks the platform team (Daily limit of a person reached).
This API key reached its daily limit of recipients. It resets at midnight UTC. An administrator can change it on the app’s page, in Apps.	The daily limit set on the app's key.	An administrator raises it on the app's page with Change limit (Apps and keys).
Sends from the free address are refused.	The free address sends to at most 100 recipients a day.	Send from your own domain (Your own domain).
Not enough emails left this month	On Free, this month's emails are used up. Received email keeps arriving.	Send later or to fewer people, or contact us to change plan (Plan and limits).
Marketing sends aren’t included in your organization’s plan. Contact us to change plan.	Your plan has no marketing sends.	Contact us to change plan. Transactional email goes out as usual.
Marketing sends start once an admin of your organization accepts the terms of service…	No administrator has accepted the terms of service yet.	An administrator accepts them at their next sign-in (Campaigns and marketing).
A free address sends transactional email only. Connect your own domain to send marketing.	Marketing was sent from the free address.	Send marketing from your own verified domain.
Publish a DMARC record for the domain before sending marketing…	The domain sends through the platform and has no DMARC record.	Publish the DMARC policy record; `p=none` is enough to start (DNS records).
This type of email is paused for the domain. Resume it on the domain page, then send again. or Sending is paused for your organization. Contact support.	Sending is paused.	See Sending is paused.
Nothing was sent: every recipient is a blocked address. See Activity › Blocked.	Every recipient is blocked. Apps get `422 ALL_RECIPIENTS_SUPPRESSED`.	Don't retry. Check each address in Activity › Blocked (Recipients bounce, or an address is blocked).
No recipient can receive email: their domains have no mail servers, or the addresses are disposable. Nothing was sent.	On a domain that sends through the platform, recipients whose domain can't receive mail are left out, and so are marketing recipients with disposable addresses.	Check the addresses with the people. They don't count as bounces, nor towards your daily limits.
Sending is being set up again after a period without activity. Try again in a few minutes.	Your Free organization was resting and is waking up. Apps and agents get `422 ORGANIZATION_RESTING`.	Try again in a few minutes (When a Free organization rests).
The sender domain is not verified yet.	The `from` address is on a domain that isn't verified.	Wait until the domain shows Verified (A domain doesn't verify).
This action is outside the allowed scope.	The key is restricted to other domains, types of email or addresses.	Use a key whose scope covers the sender, or create one on the app's page (Apps and keys).

Apps get the same reasons as error codes: the REST API reference lists them, and Moving from Postmark gives their Postmark ErrorCode.

Sending is paused

While a type of email is paused, its sends are refused and queued mail waits; received email keeps arriving. Plan › Sending › Paused sending lists each paused type with its domain, the reason and who can lift it (Plan and limits).

What paused it	Who resumes it
You or another administrator, with the Paused switch on the domain's page.	An administrator, with the same switch: You can resume it on the domain page.
A bounce rate of 4 % or a complaint rate of 0.2 % on one type of email of a domain (Sending paused on a domain).	Fix the cause first. Then an administrator, for a domain on your own sending account; the platform team, for a domain that sends through the platform.
A bounce rate of 3 % or a complaint rate of 0.08 % across your organization (Sending paused automatically).	The platform team, once you have cleaned the list.
Bounce or complaint rates, outside Mailroomly's own checks (Sending paused for bounce or complaint rates).	No one by hand: it resumes on its own once the cause is cleared.
A marketing wave that bounced too much (Marketing warm-up stopped).	The platform team, once you have cleaned the list. Transactional email is not affected.
The platform team, for all of your organization's sending, with their reason (Sending paused by the platform).	The platform team. Read the reason and contact them.
A failed health check of your organization's own sending account (Account health check failed).	It resumes on its own once the account is healthy: fix it, then select Run health check.

An automatic pause also sends a trusted account back to a new account, with lower limits, for at least 14 days (Sending trust).

Review on the newsletter lists what stops it, each with its fix (Review and send). The usual ones:

Add your postal address: fill in your Sender details (Sender details).
Nobody in this audience can be emailed: the lists are empty, or everyone on them unsubscribed, is blocked or hasn't confirmed yet (What each state means).
This month's emails left are fewer than the people this newsletter goes to: change the plan, or send it next month (Plan and limits).
A plan without marketing, the terms of service, the free address or a DMARC record: as for any marketing send (Campaigns and marketing).

A newsletter that paused while it went out says why on its page; fix it and Resume (Newsletter paused).

Someone signed up but isn't a contact yet

They are Waiting for confirmation until they click Confirm subscription in the email they got. Ask them to look in their spam folder. The same address gets at most one confirmation email a day, and the link works for 7 days; after that the sign-up is deleted and they can sign up again (Every sign-up is confirmed by email).

AI agents, apps and webhooks

An agent can't see or answer an address

Cause	What to do
The token doesn't have the Access it needs: List addresses to see the addresses, Read conversations to read them, Reply and write emails to send, Leave drafts for approval for drafts only.	Create a token with the access the agent needs, then revoke the old one in My agents (Personal tokens).
The token handles Only the ones I choose, and this address is not one of them.	Create a token that includes the address, or that handles All my addresses.
You can't open the address yourself, or only with Read only. A personal token reaches only the addresses you can open, and replying or leaving drafts needs Read and reply.	Ask an administrator for Read and reply on the address (Who can open an address).
The agent for the organization uses a key without Read inboxes or Reply from inboxes, or restricted to other addresses.	Create a key with those permissions, or restricted to this address, on the app's page, and revoke the old one (Apps and keys).
A person holds the conversation, after I’ll reply or a reply of their own. The agent is told A person is handling this conversation, so agents can’t reply in it. They can leave a draft.	Select Agents may reply in the conversation's header to hand it back (Inbox).
The agent tries to send app email with a personal token.	A personal token never sends app email: `send_message` needs an app's key with Send messages.
Personal tokens are turned off for your organization: Plan › Limits shows Turned off for this organization.	They are one of your organization's limits: an administrator contacts us to turn them on. Existing tokens don't work until then.
Conversations stay in Needs you although the agent is connected.	The agent picks up a conversation before it works on it (`claim_thread` or `claim_next_thread`); one nobody picked up stays with the people (Picking up a conversation).
Conversations come back to Needs you with CRM didn’t answer in time.	Check that the agent is connected and has the address in its scope, or ask an administrator for a longer time on the address (When an agent picks up a conversation).
The agent is told … is working on this conversation … (`CONVERSATION_CLAIMED`).	Another agent picked it up. Let that agent finish, or have it let go (`release_thread`), and work on another conversation meanwhile.

An agent is told SIGNED_IN_ONLY

Some things are never done with a token, whatever its scopes: deleting anything, creating or revoking personal tokens, revoking keys, creating keys that read mail, administrator rights, sending an address's mail to an app or a webhook, erasing a person's data, accepting the terms of service, and exporting or closing the organization. When an agent asks for one, it is refused with a message that names it and links to this manual:

SIGNED_IN_ONLY: Deleting a domain needs a person signed in to Mailroomly: ask them to do it in the web app (https://app.mailroomly.com/docs/en/ai-agents#signed-in-only)

This is expected, not a fault. Sign in to Mailroomly and do that step in the web app; the agent can carry on with the rest. The full list is in What stays with a signed-in person.

A token or a key stopped working

An agent or an app whose token or key no longer works gets 401 with INVALID_API_KEY (The API key is invalid or revoked); on the Postmark-compatible endpoints, ErrorCode 10.

Cause	What to do
The token expired: it was created with In 30 days, In 90 days or In 365 days. My agents shows when each token expires.	Create a new token in My agents and put it in the agent's configuration (Personal tokens).
You revoked it in My agents, or an administrator revoked it in Team › the person › AI agent tokens.	Create a new token. Revoking cannot be undone.
Your role or your password changed, a password reset included, or your account was disabled. A password change ends all of your tokens; a role change, being disabled or leaving ends your tokens for that organization.	Sign in again and create new tokens. Enabling an account again, or joining an organization again after leaving it, doesn't bring its old tokens back (Team).
You belong to several organizations, and the token was created in another one.	A token works only in the organization it was created in. Switch to the right one, and create a token there (Switching organization).
Personal tokens were turned off for your organization.	Ask an administrator, who contacts us. Tokens work again once personal tokens are turned on.
Your organization is being closed. Its keys and tokens stop at once.	An administrator can cancel the closing within 7 days (Export and close).
The client sends `${MAILROOMLY_TOKEN}` or a similar variable as text, because it doesn't expand variables.	Put the token itself in that client's configuration, and keep the file out of version control (Connect a client).
An app's key was replaced or revoked, or its app was deleted.	Put the current key in the app, or create a key on the app's page (Apps and keys).

A webhook keeps failing

Open Apps › For developers › Webhook deliveries, or the app's Deliveries tab. Details shows each attempt, the URL it went to and your endpoint's last answer. After 8 failed attempts in a row a delivery is marked Dead, and administrators get the notice Webhook deliveries failed (Webhook deliveries failed).

Cause	What to do
The endpoint is down, or doesn't answer with a `2xx`.	Fix the endpoint so it answers any `2xx`.
The endpoint takes longer than 10 seconds.	Answer at once, and do the work afterward.
The URL can't be reached from the internet, or points to an internal network. Such deliveries are marked Dead at once.	Use an HTTPS address reachable from the internet, with no user name or password in it.
Your endpoint refuses the signature after Rotate secret, which replaces the secret at once, retries included.	Update the secret in your endpoint (Webhooks reference).
The event never comes.	Tick it under Events to send. A test email sent as you belongs to no app, so it never reaches a webhook: use Send a test as this app (Send a test email).

Then select Send a test event on the Webhook step to see what your endpoint answers, and replay what failed: select the deliveries and choose Replay … selected, or Replay all dead for this app. Retries and replays always go to the current webhook URL. Events can arrive more than once and out of order: use each event's id to ignore repeats (Webhooks).

Signing in and the team

An invitation didn't arrive or expired

What you see	What to do
The invitation didn't arrive. The person is listed as Invited in Team.	Check the email address on their row, ask them to look in their spam folder, then choose Resend invitation. A new link goes out and the previous one stops working (Invite someone).
This invitation is not valid or has expired. Ask for a new one.	An invitation is valid for 7 days, and its link works once. An administrator chooses Resend invitation. The first administrator asks the Mailroomly team.
The person already accepted it.	They sign in on the sign-in page, or choose Forgot your password? (Signing in).
Sending the invitation is refused: This person is already in the organization.	They are in your organization already, perhaps still Invited or Disabled: find them in Team.
The invitation asks the person to sign in, not to choose a password.	They already have a Mailroomly account, in another organization: they sign in as usual, then choose Join (Someone who already has an account).
On Free, sending the invitation is refused because your plan's People are used up.	Disable someone who no longer needs access, or contact us to change plan (Plan and limits).

An invitation doesn't work while your organization is suspended. An agent with Manage the team resends an invitation with resend_invitation.

What you see	What to do
Wrong email or password.	Check both: the page doesn't say which one is wrong. Otherwise choose Forgot your password? and use the link in the email within 1 hour.
Sign-in is refused after many attempts.	After 10 attempts in one minute, wait a minute before you try again.
No reset email arrives.	The page answers the same way whether or not the address has an account. Check that you used the address you were invited with, and look in your spam folder.
A new password is refused.	A password has at least 12 characters and at most 72 bytes; accented letters and symbols count as two or three bytes.
This Google account has not been invited. Ask an administrator for an invitation.	Sign in with the Google account of the address you were invited with (Signing in).
The provider hasn’t confirmed that this email is yours, so it can’t be used here.	Sign in with a code by email or a password: some Microsoft work accounts don’t confirm the address (Signing in).
Your organization asks you to sign in with …	Your organization allows only some ways to sign in: use one of those it names (Signing in).
Your account is disabled. Contact an administrator.	An administrator disabled your account, or your organization is suspended. Ask an administrator, who can enable you again in Team (Team).
Your organization is being closed. Only its administrators can sign in.	Administrators can still sign in for 7 days, to download the data or cancel the closing (Export and close).
Your session has ended. Sign in again.	A session lasts up to 12 hours, and changing your password ends your other sessions. Sign in again.

Still stuck

Administrators: check Notices for an open notice about the problem, and Activity for the send's page.
Members: ask an administrator of your organization, who sees every address, the activity and the notices.
Write to us at hello@mailroomly.com. Say what you see, on which screen and since when; for a send, copy its Sending id from its page.