Troubleshooting

Use this guide to diagnose sending and enrollment errors.

SMTP errors

Code	Meaning	Fix
535 5.7.8	Authentication failed	Use your DID or enrolled domain as the SMTP username and check the API key. See API keys.
451 4.7.1	Warming tier rate limit	Back off and retry. See Warming tiers for caps and durations.
451 4.4.2	Queue full or transient submission error	Retry, increasing the delay between attempts.
550 5.1.0	From address not allowed	The MAIL FROM domain is not enrolled under your DID. Check that the From: address matches an enrolled domain.
550 5.7.1	Sending blocked by policy	Read the response text. Causes include recipient suppression, a paused domain, or an account safety block. See bounces and suppression.
556 5.1.10	Recipient domain does not accept mail	Correct or remove the recipient. Comail rejects IANA example domains during submission and excludes null-MX domains from sender reputation.

HTTP API errors

The HTTP API returns the same conditions as SMTP, with JSON error codes. The full table is on the Send API page.

Common errors:

• AUTH_FAILED (401): The API key is wrong. Replace it at /account.
• DOMAIN_MISMATCH (403): the From: domain is not enrolled under this DID.
• INVALID_RECIPIENT_DOMAIN (422): the recipient domain cannot receive mail; correct or remove the address rather than retrying it.
• RATE_LIMITED (429): warming tier or per-member rate limit. Retry later.
• SUSPENDED (403): the account or sending domain is blocked; check the response and /account.
• PENDING (403): account is still pending approval.
• QUEUE_FULL / TEMPORARILY_UNAVAILABLE (503): retryable; the relay is over capacity or a dependency is temporarily unavailable.

Enrollment problems

“DKIM not yet verified” after I added the records

DNS update time depends on the provider and cached records. Verify with dig:

dig +short TXT <selector>r._domainkey.yourdomain.com

If dig shows the record, wait for the labeler to check it. The labeler retries after about 30 seconds, then after 1, 2, 5, and up to 15 minutes. Refresh /account to see the status. You can also use Force re-label to request a check.

If dig shows nothing, double-check the record name. Some DNS providers strip the trailing dot or expect just the subdomain (e.g. <selector>r._domainkey rather than the full hostname).

“Domain ownership verification failed”

The relay accepts a matching AT Protocol handle or a supported domain-control TXT record. If verification fails:

• Confirm the TXT record is at the exact name shown during enrollment (some DNS providers treat @ differently).
• Run dig +short TXT _atmos-control.yourdomain.com for the dedicated control record, or check the _atproto record if you use that proof. See DNS records.
• Allow cached DNS answers to expire. The labeler retries verification automatically.
• If the page says action needed rather than “still verifying”, a record needs a change: a _atproto record on your domain points at a different account, or your SPF record contains +all. Fix the named record and wait for the next check.

“I sent mail but it didn’t arrive”

1. Check status at /account. The message will be marked sent, deferred, or bounced. See Reliability for what each means.
2. If the status is sent, the recipient’s mail server accepted the message. Check the recipient’s spam folder. If it landed in spam, see DKIM/SPF/DMARC alignment below.
3. If the status is deferred, the recipient’s MX returned a 4xx. The relay will retry. See retry schedule.
4. If the status is bounced, the relay sends a delivery status notification (DSN) to the envelope sender. For relay-submitted mail, it forwards the DSN to the domain’s forward-to mailbox if one is set. See where DSNs go.

Mail landing in spam

Possible causes:

1. Limited sending history. Comail’s default warming period is 14 days, but providers use their own rules and schedules for reputation.
2. DKIM not aligned. Check dig +short TXT <selector>r._domainkey.yourdomain.com and confirm the record is published.
3. Missing SPF. Check dig +short TXT yourdomain.com for a v=spf1 record.
4. Content. Heavy promotional language, many links, or no plain-text alternative can increase spam scores. Send a plain text version alongside HTML.

“Replies aren’t reaching me”

Reply forwarding is opt-in per domain. Confirm:

• You set a forward-to address for the domain at /account. An empty value means inbound mail bounces with 550.
• The domain’s MX record points at the relay. See Reply forwarding for the MX setup.

Back to docs