---
title: SMTP relay
description: Send through BillionSend from anything that speaks SMTP.
---

The SMTP relay takes mail from any SMTP client or framework mailer and sends it like `POST /emails`: same sender checks, suppressions, plan limits and events.

## Connect

| Setting | Value |
| --- | --- |
| Host | `smtp.billionsend.com` |
| Port, STARTTLS | `587` |
| Port, implicit TLS | `465` |
| Username | `billionsend` |
| Password | An [API key](/docs/api-reference/basics) (`bs_...`) |

TLS is required on both ports. A key that is sending only, or limited to one domain or one inbox, keeps those limits over SMTP.

```bash
curl --ssl-reqd smtp://smtp.billionsend.com:587 \
  --user "billionsend:$BILLIONSEND_API_KEY" \
  --mail-from hello@mail.example.com \
  --mail-rcpt user@example.org \
  -T message.eml
```

## What the relay checks

- The `From` address must belong to a [verified domain](/docs/concepts/domains) of the key's team.
- A non-empty `Subject` and an HTML or text body are required.
- A message can be up to 40 MiB with up to 50 recipients.
- Attachments follow the same rules as the API: programs and disguised file types are refused.
- Headers follow the same allowlist as `POST /emails` (`X-*` names, threading, priority, `List-Unsubscribe`). BillionSend writes every other header itself.
- Three failed logins close the connection. A session lasts at most 15 minutes, and one IP address can hold at most 10 connections.

## Rate limits and retries

Messages count against the same per-minute limit as the key's API requests. Over it, the relay answers `451 4.7.1` with the seconds to wait. SMTP clients retry this on their own.

If a client never saw the final `250` and resends the same message with the same `Message-ID`, it gets the first answer back instead of a second email.

## Errors

| Reply | Meaning |
| --- | --- |
| `530` / `535` | Missing or wrong credentials |
| `550` | Sender not allowed for this key, or a recipient that cannot receive mail |
| `552` | Message or attachment too large |
| `553` | Missing subject or malformed address |
| `554` | Message refused, for example an unverified sender domain or a header that is not allowed |
| `451`, `452` | Temporary: rate limit or capacity. Retry. |
