> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brudcast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email troubleshooting

> Send API and SMTP error messages, domain setup failures and delivery problems, with why each happens and how to fix it.

Find the message or symptom you're seeing. Each entry says why it happens and what to do. This page
holds the full answer for every email error, and the setup pages link back to it.

## Domain setup

### Adding a domain

<AccordionGroup>
  <Accordion title="“mail.example.com is a Brudcast-owned domain and cannot be added”" icon="circle-alert">
    **Why:** the name is, or sits under, a domain Brudcast owns, such as `brudcast.com`,
    `brudcast.io`, `brudcast.org`, `brudcast.app` or `brudcastmail.com`.

    **Fix:** add a domain your organization owns. Use a subdomain dedicated to sending, such as
    `mail.example.com`. See [Add a sending domain](/channels/email/add-a-sending-domain).
  </Accordion>

  <Accordion title="“Domain mail.example.com is already added to your account”" icon="circle-alert">
    **Why:** the domain is already in your **Domains** list. A domain can be added once.

    **Fix:** open the existing domain instead of adding it again.
  </Accordion>

  <Accordion title="The Add Domain button is disabled" icon="circle-alert">
    **Why:** the organization has no active Email subscription, the subscription is past due, or
    you've reached the number of sending domains your plan allows. Hover over the button to see
    which. The managed sending address doesn't count toward the limit.

    **Fix:** subscribe, update your payment method, or move to a larger plan under
    **Billing & Plans**. See [Plans and subscriptions](/billing/plans-and-subscriptions).
  </Accordion>

  <Accordion title="The domain shows Failed straight after you add it" icon="circle-alert">
    **Why:** provisioning didn't complete, so the domain is `provisioning_failed` and its keys and
    records were never generated.

    **Fix:** email [support@brudcast.com](mailto:support@brudcast.com) with the domain name. Don't
    delete and re-add the domain.
  </Accordion>
</AccordionGroup>

### Verifying DNS records

The domain's status depends on one record: the SPF delegation CNAME at `brd.spf.<your domain>`. DKIM,
DMARC and tracking are checked and shown separately, and a domain can be **Verified** while they're
still missing.

<AccordionGroup>
  <Accordion title="The domain shows Failed after you run Verify DNS" icon="circle-alert">
    **Why:** the lookup of `brd.spf.<your domain>` didn't return the expected target. The usual
    causes, in order:

    * The record isn't published yet, or was added to the wrong zone. Records count only at the
      provider your name servers point to.
    * The name is doubled, as in `brd.spf.mail.example.com.example.com`, because you typed the full
      name into a provider that adds the zone itself.
    * On Cloudflare, the record is proxied (the orange cloud).
    * Another record already exists at that name, so the CNAME wasn't saved.

    **Fix:** check with `dig +short CNAME brd.spf.mail.example.com`, correct the record, and select
    **Verify DNS** again. The per-provider steps and each provider's trap are in
    [Publish DNS records at your provider](/channels/email/dns-by-provider).
  </Accordion>

  <Accordion title="The domain stays Pending after you published the records" icon="circle-alert">
    **Why:** a domain in `unverified` also shows **Pending**. Brudcast only checks your DNS when you
    ask it to.

    **Fix:** open the domain and select **Verify DNS**. See
    [Verify your domain](/channels/email/verify-your-domain).
  </Accordion>

  <Accordion title="DKIM stays “Not yet verified”" icon="circle-alert">
    **Why:** one or both of `brd1._domainkey` and `brd2._domainkey` is missing, proxied, or points
    somewhere else.

    **Fix:** publish both CNAMEs exactly as shown on the **DNS Records** tab. The domain can be
    **Verified** without them, but receiving servers can't check your DKIM signature until they're
    published, and your mail fails DKIM.
  </Accordion>

  <Accordion title="DMARC stays “Not yet verified”" icon="circle-alert">
    **Why:** the `_dmarc` TXT record is missing, or a different DMARC record is there. Brudcast
    compares the whole value, so your own policy doesn't match the generated one.

    **Fix:** a domain can have only one DMARC record. Publish the generated value, or keep your own
    policy and accept that this check stays unverified. It doesn't stop the domain from verifying.
    On Route 53, the value has to be wrapped in double quotes.
  </Accordion>

  <Accordion title="Tracking stays “Not yet verified”" icon="circle-alert">
    **Why:** the tracking CNAME is missing, or you changed the tracking hostname and haven't
    published the new record yet.

    **Fix:** publish the CNAME shown under **Tracking records**, then verify again. Don't turn
    tracking on until it's verified, or the tracked links in your mail break. See
    [Tracking and unsubscribes](/channels/email/overview#tracking-and-unsubscribes).
  </Accordion>

  <Accordion title="dig shows the right value but the check still fails" icon="circle-alert">
    **Why:** your machine may be reading a cached answer, or the change hasn't reached every
    resolver yet.

    **Fix:** wait up to an hour and run **Verify DNS** again. If it still fails, email
    [support@brudcast.com](mailto:support@brudcast.com) with the domain name and your `dig` output.
  </Accordion>
</AccordionGroup>

### After the domain is verified

<AccordionGroup>
  <Accordion title="A domain that was verified now shows Failed" icon="circle-alert">
    **Why:** the domain has been suspended, usually because its bounce or complaint rate went over
    the limit. A suspended domain's mail is refused: `403` on the send API, `550` on SMTP.

    **Fix:** see [Deliverability overview](/deliverability/overview). A suspended domain recovers
    after 24 hours back below the warning level.
  </Accordion>

  <Accordion title="The SMTP Credentials or Sending Keys tab is locked" icon="circle-alert">
    **Why:** you're looking at the Brudcast trial address, which can only send campaigns.

    **Fix:** add and verify a domain of your own. See
    [The managed sending address](/channels/email/overview#the-managed-sending-address).
  </Accordion>
</AccordionGroup>

## Send API errors

| Status | Message                                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `From address domain 'x' does not match sending key domain 'y'`, `Domain x is not registered`, `From address domain 'x' is not owned by the sending key's organization` |
| 401    | `Unauthorized`                                                                                                                                                          |
| 403    | `Sending is disabled for this account: …`                                                                                                                               |
| 422    | `Validation error`                                                                                                                                                      |
| 429    | `Too many failed attempts, please try again later`, `Too many requests, please try again later.`, `Rate limit exceeded: …`                                              |
| 500    | `An unexpected error occurred`                                                                                                                                          |

<AccordionGroup>
  <Accordion title="“Unauthorized”" icon="circle-alert">
    **Why:** the sending key is missing, mistyped, deleted, regenerated, or still **Provisioning**.
    The send API only reads the key from `Authorization: Bearer`, so an `X-API-Key` header isn't
    enough.
    **Fix:** send `Authorization: Bearer your_sending_key` with a key that shows **Active**. See
    [Sending keys](/channels/email/domain-api-keys).
  </Accordion>

  <Accordion title="“Too many failed attempts, please try again later”" icon="circle-alert">
    **Why:** more than 20 requests from your IP address failed authentication within 15 minutes.
    **Fix:** fix the key, then wait before trying again.
  </Accordion>

  <Accordion title="“Too many requests, please try again later.”" icon="circle-alert">
    **Why:** your IP address sent more than 30 requests a minute to the send endpoint, or more than
    1,000 a minute in total.
    **Fix:** slow down. One request can carry several recipients. See
    [Rate limits](/developers/rate-limits).
  </Accordion>

  <Accordion title="“Rate limit exceeded: …”" icon="circle-alert">
    **Why:** your organization went over a sending limit. The message ends with the window:
    `perSecond`, `perMinute`, `perHour`, `perDay` or `perMonth`. The second, minute and hour windows
    count API calls. The day and month windows count recipients (To, Cc and Bcc together). All
    windows use UTC.
    **Fix:** retry after the window resets. New accounts start with lower daily limits. See
    [New-account sending limits](/deliverability/new-account-sending-limits).
  </Accordion>

  <Accordion title="“Validation error”" icon="circle-alert">
    **Why:** the body is missing something or breaks a limit. The `errors` array names the field.
    Common causes: no `from`, no `to`, no `subject`, neither `text` nor `html`, a body over 10 MB,
    or a header name longer than 78 characters.
    **Fix:** correct the field named in `errors`. See
    [Send email over HTTP](/developers/sending/http-api).
  </Accordion>

  <Accordion title="“From address domain 'x' does not match sending key domain 'y'”" icon="circle-alert">
    **Why:** a domain sending key can only send from its own domain.
    **Fix:** use the key that belongs to the domain in your `from` address, or create one on that
    domain.
  </Accordion>

  <Accordion title="“Domain x is not registered”" icon="circle-alert">
    **Why:** the domain in your `from` address isn't a sending domain in Brudcast. Check for a typo,
    or whether the domain was deleted.
    **Fix:** send from one of the domains on the **Domains** tab.
  </Accordion>

  <Accordion title="“From address domain 'x' is not owned by the sending key's organization”" icon="circle-alert">
    **Why:** you used an organization-wide key, and the `from` domain belongs to no sending domain in
    that organization.
    **Fix:** send from one of your organization's domains, or add the domain first.
  </Accordion>

  <Accordion title="“Sending is disabled for this account: …”" icon="circle-alert">
    **Why:** the text after the colon says which:

    * `account suspended`: your organization's sending has been suspended.
    * `account status cannot be verified right now`: a temporary problem on Brudcast's side.
    * `sending domain is suspended for bounce or complaint rates`: the domain's reputation crossed
      the suspension level.

    **Fix:** for a suspended account, email [support@brudcast.com](mailto:support@brudcast.com). For the
    temporary problem, retry later. For a suspended domain, see
    [Deliverability overview](/deliverability/overview).
  </Accordion>

  <Accordion title="“An unexpected error occurred”" icon="circle-alert">
    **Why:** something failed on Brudcast's side.
    **Fix:** retry. If it keeps happening, email [support@brudcast.com](mailto:support@brudcast.com) with the
    time of the request.
  </Accordion>
</AccordionGroup>

## SMTP relay errors

<AccordionGroup>
  <Accordion title="“538 Must issue a STARTTLS command first”" icon="circle-alert">
    **Why:** your client tried to log in before encrypting the connection, on port 587, 2525 or 25.
    **Fix:** turn on STARTTLS (sometimes called "TLS required"), or use port 465 with TLS from the
    start.
  </Accordion>

  <Accordion title="“Invalid credentials”" icon="circle-alert">
    **Why:** the username or password is wrong, or the SMTP user was deleted or its password
    regenerated.
    **Fix:** use the generated SMTP username, which looks like `3f9a1c7e@mail.example.com`, not your
    own email address. If you've lost the password, regenerate it. See
    [SMTP users](/channels/email/smtp-users).
  </Accordion>

  <Accordion title="“Authentication failed”" icon="circle-alert">
    **Why:** a temporary problem on Brudcast's side while checking your login.
    **Fix:** retry. If it persists, email [support@brudcast.com](mailto:support@brudcast.com).
  </Accordion>

  <Accordion title="“550 MAIL FROM domain does not match authenticated domain”" icon="circle-alert">
    **Why:** the envelope sender is on a different domain from the SMTP user.
    **Fix:** send from an address on the SMTP user's domain, or use an SMTP user created on the other
    domain.
  </Accordion>

  <Accordion title="“550 Domain x not registered”" icon="circle-alert">
    **Why:** the envelope sender's domain isn't a sending domain in Brudcast.
    **Fix:** check the address your application sends from.
  </Accordion>

  <Accordion title="“550 Sending is disabled for this account: …”" icon="circle-alert">
    **Why and fix:** the same as the send API error of the same name, above.
  </Accordion>

  <Accordion title="“451 Rate limit exceeded: …”" icon="circle-alert">
    **Why:** your organization went over a sending limit. `451` asks your client to queue the
    message and try again later, so most mail libraries retry by themselves.
    **Fix:** let the client retry. Each SMTP transaction counts once against the limits.
  </Accordion>

  <Accordion title="“550 Missing From address”" icon="circle-alert">
    **Why:** the message has no `From` header.
    **Fix:** set a From address on the message itself, not only in the envelope.
  </Accordion>

  <Accordion title="“451 Failed to queue message”" icon="circle-alert">
    **Why:** a temporary problem accepting the message.
    **Fix:** let your client retry.
  </Accordion>

  <Accordion title="Bcc recipients never receive the message" icon="circle-alert">
    **Why:** the relay rebuilds the message from its To and Cc headers. Recipients given only in the
    SMTP envelope aren't delivered.
    **Fix:** put every recipient in To or Cc, or use the send API, which supports `bcc`.
  </Accordion>

  <Accordion title="Reply-To or custom headers are missing" icon="circle-alert">
    **Why:** the relay drops `Reply-To` and custom headers when it rebuilds the message.
    **Fix:** use the send API, which accepts `replyTo` and `headers`.
  </Accordion>
</AccordionGroup>

## Delivery and tracking

<AccordionGroup>
  <Accordion title="The API returned 202 but nothing arrived" icon="circle-alert">
    **Why:** `202` means queued, not delivered. Recipients on your suppression list are dropped
    without an error, and if every recipient is suppressed, nothing is sent. The receiving server
    may also have bounced or deferred the message.
    **Fix:** look the message up in [Message status](/developers/sending/message-status), or
    subscribe to the `email.delivered`, `email.bounced` and `email.dropped`
    [webhook events](/developers/webhooks/overview). Check your
    [suppression list](/contacts/suppressions).
  </Accordion>

  <Accordion title="Mail lands in spam" icon="circle-alert">
    **Why:** usually authentication, content or list quality.
    **Fix:** send to an address you control and check that SPF, DKIM and DMARC pass in the raw
    headers. Then see [Deliverability best practices](/deliverability/best-practices).
  </Accordion>

  <Accordion title="Opens and clicks are always zero" icon="circle-alert">
    **Why:** for API and SMTP mail, **Open Tracking** and **Click Tracking** are off by default. For
    campaigns, **Track opens** or **Track clicks** may be off. Tracking also needs an HTML part.
    **Fix:** see [Tracking and unsubscribes](/channels/email/overview#tracking-and-unsubscribes).
  </Accordion>

  <Accordion title="Opens and clicks are credited to the wrong recipient" icon="circle-alert">
    **Why:** on an API send to several recipients, every open and click is credited to the first
    address in `to`.
    **Fix:** send one message per recipient.
  </Accordion>

  <Accordion title="Tracked links in my email don't open" icon="circle-alert">
    **Why:** tracking is on, but the tracking CNAME isn't published, so `track.<your domain>`
    doesn't resolve.
    **Fix:** publish the tracking record and verify it, or turn **Click Tracking** off until you do.
  </Accordion>

  <Accordion title="My emails say “via Brudcast”, or my from address changed" icon="circle-alert">
    **Why:** the campaign sends from the Brudcast trial address, which has a fixed address and
    display name.
    **Fix:** verify your own domain. See
    [The managed sending address](/channels/email/overview#the-managed-sending-address).
  </Accordion>

  <Accordion title="Bounces from one mailbox provider only" icon="circle-alert">
    **Why:** usually reputation or that provider's policy rather than your setup.
    **Fix:** check the bounce reasons in
    [Bounces, complaints and suppression](/deliverability/bounces-complaints-and-suppression), then
    [Deliverability best practices](/deliverability/best-practices).
  </Accordion>
</AccordionGroup>

## Still stuck

Email [support@brudcast.com](mailto:support@brudcast.com) with:

* the sending domain
* the `jobId`, or the campaign name
* the time you sent, with your time zone
* the recipient address
* the exact error text

## Related

<Columns cols={2}>
  <Card title="Verify your domain" icon="circle-check" href="/channels/email/verify-your-domain">
    Run the check and read each result.
  </Card>

  <Card title="DNS by provider" icon="server" href="/channels/email/dns-by-provider">
    Publish the records at Cloudflare, Route 53, Namecheap, GoDaddy and others.
  </Card>

  <Card title="Send your first email" icon="send" href="/channels/email/send-your-first-email">
    Campaign, API or SMTP.
  </Card>

  <Card title="Deliverability overview" icon="shield-check" href="/deliverability/overview">
    Reputation, suspension and bounce rates.
  </Card>
</Columns>