Troubleshooting

Domain stays pending

Check the status of MX, DKIM, SPF, and DMARC separately in Settings → Domains. Compare host, type, and value character for character. Look for providers that appended the root domain twice, flattened a CNAME, or left an old conflicting MX record.

Public DNS caches can lag behind the provider dashboard. Wait for the record TTL and check again before repeatedly replacing correct values.

Incoming mail does not appear

Confirm that the domain is verified, the exact recipient mailbox exists, and public MX points to Startup Mail. Test from an unrelated provider and check the sender for a bounce. Startup Mail does not catch all unknown local parts.

Large or unsafe messages can be rejected or quarantined before they reach the inbox.

A message will not send

Check the visible error code and workspace status. Common causes are missing mailbox permission, expired trial or inactive billing, an already-suppressed recipient, a daily or monthly cap, too many recipients, or a message over the size boundary.

If workspace sending is paused, incoming mail remains available. Contact support for reputation review rather than repeatedly retrying the same recipient.

Forwarding stopped

Startup Mail disables a destination after a hard bounce. Confirm the external address can receive mail, then request and complete a new six-digit verification. Remember that forwarding does not synchronize read state or sent folders.

API returns 401 or 403

• 401 usually means the Bearer key is missing, invalid, revoked, or expired.
• 403 with insufficient_scope names the exact scope the route needs.
• A key can have the right scope but still lack access to a private mailbox.

Create or rotate keys in Settings → Developers. Do not broaden a key unless the workload truly needs the operation.

Webhook deliveries fail

The endpoint must be public HTTPS, return 2xx quickly, and accept the raw JSON body. Verify against the raw bytes before parsing. Failed requests retry up to five times; make the handler idempotent with StartupMail-Delivery.

Ask for help

Email hello@startupmail.dev with the workspace name, approximate timestamp, affected address, endpoint, and x-request-id when available. Never include a full API key or webhook signing secret.