> ## 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.

# SMTP relay

> Send through Brudcast from any SMTP client: host, ports, TLS, authentication, limits, and what the relay doesn't carry over.

export const Screenshot = ({id, src, srcDark, alt, caption}) => {
  if (!src) {
    return <Placeholder id={id} kind="screenshot" label="Screenshot coming soon" description={alt} icon={<ImageIcon />} />;
  }
  return <figure className="brd-media" data-media-id={id}>
      <img className="brd-media-frame block dark:hidden" src={src} alt={alt} />
      <img className="brd-media-frame hidden dark:block" src={srcDark || src} alt={alt} />
      {caption && <figcaption className="brd-media-caption">{caption}</figcaption>}
    </figure>;
};

Point any SMTP client at the Brudcast relay to send from your verified domain. Use it when your
software can't call an HTTP API.

<Screenshot id="ss-developers-smtp-relay-hero" alt="The SMTP Credentials tab on a verified domain, listing one SMTP user" />

<Info>
  **Before you start**, you need your own verified sending domain. The **Brudcast trial address**
  has no SMTP credentials. See [Email overview](/channels/email/overview).
</Info>

## Connection settings

| Setting        | Value                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------- |
| Host           | `out-smtp.prod.brudcast.com`                                                                  |
| Port           | `587`, `2525` or `25` with STARTTLS, or `465` with TLS from the start                         |
| Authentication | `PLAIN` or `LOGIN`                                                                            |
| Username       | The SMTP user's username, shown when you create it. It looks like `a1b2c3d4@mail.example.com` |
| Password       | The SMTP user's password: 32 characters, shown once                                           |

<Note>
  If the **SMTP Settings** panel on your domain shows a different host name, use
  `out-smtp.prod.brudcast.com`.
</Note>

### Choosing a port

* **587** is the standard submission port. Start here.
* **2525** works the same way. Use it when a network blocks 587.
* **465** encrypts from the first byte. Use it when your client calls this "SSL" or "implicit TLS".
* **25** works, but many cloud providers and ISPs block outgoing traffic on it.

On 587, 2525 and 25 your client must send `STARTTLS` before it logs in. If it tries `AUTH` on an
unencrypted connection, the relay replies `538 Error: Must issue a STARTTLS command first`. That
keeps your password from ever crossing the network in the clear.

## Get SMTP credentials

<Steps>
  <Step title="Open the domain">
    Go to **Channels > Email**, open the **Domains** tab and select your domain.
  </Step>

  <Step title="Add an SMTP user">
    Open the **SMTP Credentials** tab and select **Add New SMTP User**. Give it a name that says
    which application will use it.
  </Step>

  <Step title="Copy the credentials">
    Copy the username and password. The password is shown only once.
  </Step>
</Steps>

See [SMTP users](/channels/email/smtp-users) to regenerate a password or deactivate a user.

## Rules

* **The envelope sender must be on the SMTP user's domain.** Otherwise the relay rejects
  `MAIL FROM` with `550 MAIL FROM domain does not match authenticated domain`. Use an address on the
  same domain in the `From` header too.
* **Messages can be up to 25 MB**, including attachments.
* **A message must have a `From` header.** Without one, the relay replies
  `550 Missing From address`.
* **A missing subject becomes `(no subject)`.** A message with no text or HTML part is sent with an
  empty text body.

## What the relay doesn't carry over

The relay doesn't forward your message byte for byte. It reads the From, To and Cc headers, the
subject, the text and HTML parts and the attachments, then builds a new message from those. Brudcast
signs and tracks that new message.

Anything else is lost:

<Warning>
  * **Bcc recipients aren't delivered.** Recipients that appear only in the SMTP envelope
    (`RCPT TO`), and not in a To or Cc header, are dropped. This is how most libraries send Bcc.
  * **`Reply-To` is dropped.** Replies go to the From address.
  * **Custom headers are dropped**, including any `List-Unsubscribe` you set yourself.

  If you need any of these, use the [email send API](/developers/sending/http-api). It accepts
  `bcc`, `replyTo` and custom `headers`.
</Warning>

## Limits

Your organization's sending limits apply to SMTP the same as to the API. The relay counts them once
per SMTP transaction, when your client sends `MAIL FROM`, whatever the number of recipients.

Over a limit, the relay replies `451 Rate limit exceeded: <window>`, for example
`451 Rate limit exceeded: perMinute`. `451` is temporary: your client or mail server queues the
message and tries again later. See [Rate limits](/developers/rate-limits).

## Replies you might see

| Reply                                                      | Meaning                                                                            |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `535 Invalid credentials`                                  | Wrong username or password, or the SMTP user is deactivated                        |
| `538 Error: Must issue a STARTTLS command first`           | Run `STARTTLS` before `AUTH` on ports 587, 2525 and 25                             |
| `550 MAIL FROM domain does not match authenticated domain` | Send from an address on the SMTP user's domain                                     |
| `550 Domain x not registered`                              | The domain isn't set up in Brudcast                                                |
| `550 Sending is disabled for this account: <reason>`       | The account is suspended, or the domain is suspended for bounce or complaint rates |
| `451 Rate limit exceeded: <window>`                        | A sending limit is used up. Your client retries                                    |
| `451 Failed to queue message`                              | A temporary failure. Your client retries                                           |

See [Errors](/developers/errors#smtp-relay-replies) for the full list.

## What happens next

The relay accepts the message as soon as it's queued. Delivery to each recipient's mail server
happens next. SMTP gives you no job ID, so use the
[message log](/developers/sending/message-status) (filter by `recipient`) or
[webhooks](/developers/webhooks/overview) to follow up.

## Related

<Columns cols={2}>
  <Card title="Framework settings" icon="blocks" href="/developers/sending/integrations">
    Copy-paste configuration for Nodemailer, Laravel, Django, Rails, WordPress and PHPMailer.
  </Card>

  <Card title="Email send API" icon="send" href="/developers/sending/http-api">
    The HTTP alternative that keeps Bcc, Reply-To and headers.
  </Card>

  <Card title="SMTP users" icon="key-round" href="/channels/email/smtp-users">
    Create, regenerate and deactivate SMTP credentials.
  </Card>
</Columns>