Troubleshooting
What each preflight check means, and how to fix the ones that fail.
Ask your agent to “run doctor” at any time. prepare_send runs the same checks, and a failing check blocks a send. A warning doesn’t block it, but is worth fixing.
Preflight checks
Settings
Fails when Sendoff has no settings yet. Ask the agent to set the name and sender, or run bun run setup again.
Postal address
Warns when there’s no postal address. That’s fine for email that isn’t commercial; prepare_send checks each issue and blocks any that read as commercial. See When you need a postal address.
Subscribers
Fails when nobody is active. Import your list, or share your signup page.
SES account
Fails when Sendoff can’t reach SES at all, usually because the Worker’s AWS key was deleted or the region is wrong. Run bun run setup again to recreate the key.
SES production access
Fails while the account is in the SES sandbox, where it can only send to verified addresses. Request production access (setup offers to) and wait for AWS to approve it, which usually takes about a day.
SES sending
Fails when sending is disabled for the account. Check the SES console and any email from AWS about it.
SES account health
Warns when AWS has put the account on probation because of bounces or complaints, and fails when it has shut sending down. Look at the bounce and complaint rates in the SES console’s reputation dashboard, clean the list, and reply to AWS’s email.
Sending quota
Fails when there are more active subscribers than emails left in today’s SES quota. Wait for the quota to reset, or ask AWS for a higher one in the SES console.
Suppression list
Warns when SES’s account-level suppression list is off. Setup turns it on; it’s a second line of defense against emailing bad addresses.
Sender identity
Fails when the sender’s domain isn’t in SES, or isn’t verified yet. Check that the DKIM records exist in DNS. Run bun run setup again to see which are missing.
Custom MAIL FROM
Warns when the MAIL FROM domain isn’t set up or verified. Without it, SPF doesn’t align with your domain. Check the MX and TXT records on bounce.<your domain>.
DMARC
Fails when your domain has no DMARC record. Gmail, Yahoo and Outlook require one for bulk mail. Add a TXT record at _dmarc.<your domain> with v=DMARC1; p=none.
Bounce and complaint tracking
Warns when bounces and complaints won’t reach Sendoff, so bad addresses won’t be suppressed. Fails when the configuration set is missing, since sends that name it fail. Run bun run setup again.
Delivery reports
Warns when SES doesn’t report deliveries to Sendoff, so issue stats can’t count how many emails arrived. Instances set up before Sendoff counted deliveries need it. Run bun run setup again to turn them on.
Common problems
Setup stopped partway. Run bun run setup again from your Sendoff folder, or bun create sendoff again from where you first ran it. It skips everything that’s done and continues from the step that failed.
Setup gave up waiting for your hostname to come online. A new hostname needs a few minutes for its certificate. If your DNS isn’t on Cloudflare, check that the CNAME from your hostname to the *.pages.dev address is in place, and that your hostname is listed under the sendoff-pages project’s custom domains in the Cloudflare dashboard. Then run bun run setup again.
The agent can’t connect. Check the URL ends in /mcp and the header is Authorization: Bearer <token>, with a space after Bearer. If you’ve lost the token, replace it.
A test email didn’t arrive. Check spam. While the account is in the SES sandbox, tests only reach addresses verified in SES, which your sender domain counts as. If SES refused it, the agent saw the reason when it sent the test; doctor shows anything else in the way.
prepare_send says the issue reads as commercial. You have no postal address, and the issue reads as promoting something. Add an address with your agent (“set my postal address to …”), or follow the fixes it lists, such as leading with your own update and keeping the product to a short mention. Then send another test.
Sending stopped. Ask for send_status, which says why it stopped. Fix the cause, such as a raised quota or a re-enabled account, then ask the agent to resume.
The preview shows an old version, dimmed. The latest edit has a Markdown problem. The preview lists it with a line number, and the agent can fix it.
“Send a test first” when preparing. Something changed since the last test: the draft, or a setting like the accent color. Send another test of the current version.