---
title: "Troubleshooting"
description: "Fixes for the problems that come up most: emails not sending, domain verification, bounces."
source: "https://www.mailmark.dev/docs/troubleshooting"
site: "Mailmark"
---

# Troubleshooting

Common issues and how to resolve them.

## Emails not sending

If an API call returns an error or emails never arrive, work through this checklist:

- **API key is valid and not revoked.** Go to Dashboard -> Developer and confirm the key is listed and not revoked. If you lost the key, revoke it and create a new one; keys are shown only once.
- **The sender address exists as a mailbox.** The `from` address must be a real mailbox on the domain the API key is scoped to. Check Dashboard -> Mailboxes.
- **Domain is verified and active.** An unverified domain cannot send email. The domain status must be Active in Dashboard -> Domains.
- **API key is scoped to the correct domain.** Each domain-scoped API key is tied to exactly one domain. If the `from` address is on a different domain, the request is rejected with a 403.
- **scheduledAt is not in the past.** If you passed `scheduledAt`, it must be a future Unix millisecond timestamp.
- **Either html or text is provided.** The send endpoint requires at least one of `html` or `text`. An empty body returns 400.

A 401 Unauthorized means the API key is invalid or revoked. A 403 Forbidden means the sender address does not belong to the key's domain.

## Domain verification issues

- **DNS record not found.** After adding a TXT record, confirm it is visible with `dig TXT yourdomain.com` or MXToolbox. If it is not, check that you saved the record at your DNS provider.
- **Record added to the wrong subdomain.** The verification TXT record belongs on the root domain (`@`) unless Mailmark instructs otherwise.
- **Multiple conflicting SPF records.** A domain can only have one SPF TXT record. Merge them: `v=spf1 include:amazonses.com include:other-provider.com ~all`.
- **TTL caching delay.** DNS records are cached for their TTL. Wait for it to expire before re-verifying; a common TTL is 3600 seconds.
- **Domain registrar propagation.** Some registrars are slow. If dig shows the record but Mailmark still shows unverified, click Verify now again; Mailmark re-checks on demand.

## Bounces & rejections

A hard bounce means the recipient address does not exist or the server permanently rejected the email. A soft bounce is a temporary failure (mailbox full, server temporarily unavailable).

- **Check the recipient address.** The most common cause of bounces is a typo in the `to` field.
- **Your domain is not warmed up.** Start with small volumes and increase gradually, or use [warmup](/docs/warmup). A large blast from a brand-new domain triggers spam filters and rejections.
- **SPF or DKIM is not configured.** Receiving servers check both before accepting email. Verify your DNS setup in [Domain Setup](/docs/domain-setup#spf-dkim).
- **Recipient marked you as spam.** Their provider may automatically reject future sends. Remove unengaged recipients regularly.
- **Content triggers spam filters.** Avoid excessive caps, suspicious links, and spam trigger words. Test with the [spam score tester](/tools/spam-score-tester) before sending to a large list.

Repeated hard bounces damage your domain's sending reputation. Remove bounced addresses from your recipient lists immediately. Query them with `GET https://api.mailmark.dev/v1/bounces`.

## Still stuck?

Support typically responds within 2 hours on business days: [contact support](/contact).

---

Mailmark - email hosting and campaigns for your own domain. Canonical page: https://www.mailmark.dev/docs/troubleshooting | [llms.txt](https://www.mailmark.dev/llms.txt) | [OpenAPI](https://www.mailmark.dev/openapi.json) | [sitemap](https://www.mailmark.dev/sitemap.xml)