---
title: "SMTP"
description: "OneSend uses SMTP in two directions: apps can send through OneSend over SMTP, and OneSend can send through any SMTP server as a provider."
url: https://onesend.email/docs/smtp/
---
# SMTP

OneSend uses SMTP in two directions: apps can send through OneSend over SMTP, and OneSend can send through any SMTP server as a provider.

<a id="smtp-ingress"></a>
## 1. SMTP ingress: send from apps that only support SMTP

WordPress, Ghost, Supabase Auth, Keycloak, cron scripts and other software that can send through SMTP can use your routing policy, failover and logs.

| Setting | Value |
|---|---|
| Host | Your OneSend host |
| Port | `2587` (`ONESEND_SMTP_PORT`) |
| Security | STARTTLS when TLS is configured (see [TLS](#tls)); without TLS, only clients on the same host can authenticate |
| Username | Any value, for example `onesend` |
| Password | A OneSend API key with Full access or Sending only (`os_live_…`, or `os_test_…` for test sends that are not delivered) |

Optional headers on the message:

- `X-OneSend-Tags: signup,welcome`
- `X-OneSend-Policy: transactional` (the routing policy to use)
- `X-OneSend-Type: broadcast` (marks the message as marketing; the default is transactional)

Messages sent through SMTP appear in **Logs** with source `smtp`. Messages up to 25 MB are accepted; larger ones are refused with `552 5.3.4` during `DATA`. Each SMTP server accepts at most 200 connections at a time, and the inbound receiver at most 100 recipients per message.

When a message is refused after `DATA`, the reply says whether to try again. Conditions that pass by themselves are temporary, so SMTP clients keep the message and retry: `452 4.3.1` when the plan's monthly emails are used (`email_limit`, cloud), `451 4.7.1` when the key's hourly or daily send limit is reached (`key_rate_limited`), and `451 4.3.0` for a server error. Every other refusal is permanent, `550`, with OneSend's message: no plan or license key for live email (`plan_required`, `license_required`), a sender domain outside the plan (`domain_limit`), a sender domain or recipient the key may not use, or no sending provider for the From domain (`no_provider_for_domain`). The same rules apply as for `POST /v1/emails`: an expired key, or one used from an address it does not allow, cannot sign in (`535`), nor can a session token that did not pass two-factor authentication in a workspace that requires it.

<a id="tls"></a>
### TLS

STARTTLS is available only when both `ONESEND_SMTP_TLS_KEY` and `ONESEND_SMTP_TLS_CERT` point to a PEM key and certificate:

```bash
ONESEND_SMTP_TLS_KEY=/etc/onesend/smtp.key
ONESEND_SMTP_TLS_CERT=/etc/onesend/smtp.crt   # full chain
```

With TLS configured, the server offers STARTTLS and accepts AUTH only after STARTTLS, so the API key is never sent in plain text.

Without these variables, STARTTLS is not offered, and AUTH is accepted only from clients on the same host (loopback). Clients on other hosts are refused, because the API key would cross the network unencrypted. In Docker, connections from the host machine or other containers are not loopback connections. To use SMTP ingress from other hosts:

- configure TLS as above (recommended), or
- on a trusted private network only, set `ONESEND_SMTP_ALLOW_INSECURE_AUTH=true` to accept AUTH without TLS.

The bundled `docker-compose.yml` sets `ONESEND_SMTP_ALLOW_INSECURE_AUTH` to `true` unless `.env` sets it, and publishes port 2587 on the host's loopback interface only (`127.0.0.1:2587:2587`), so apps on the Docker host can authenticate without TLS. If you publish the port on other interfaces, configure TLS and set `ONESEND_SMTP_ALLOW_INSECURE_AUTH=false` in `.env`.

The loopback rule trusts the TCP peer address. Behind a TCP proxy on the same host (sslh, HAProxy in TCP mode, Docker's userland proxy), every client appears to come from `127.0.0.1`, so AUTH without TLS would be accepted from anywhere. Configure TLS in that setup.

If you do not use SMTP ingress, disable it with `ONESEND_SMTP_PORT=0`, or remove the `2587` port mapping from `docker-compose.yml`.

Use a certificate for the host name that apps connect to. The same certificate can serve the inbound receiver (`ONESEND_SMTP_IN_PORT`), which also offers STARTTLS when TLS is configured.

<a id="smtp-provider"></a>
## 2. Any SMTP server as a provider

Open **Sending providers**, select **Connect provider**, choose **SMTP**, and enter the host, port, security, username and password. Use this for mailbox services you already pay for, or for a relay that has no HTTP API.

### Gmail

- **Personal Gmail (@gmail.com):** SMTP `smtp.gmail.com:465` with an [app password](https://support.google.com/accounts/answer/185833), which requires 2-Step Verification. Google's limit is about 500 recipients per day, and the account is for personal use. Google's terms do not allow bulk or automated marketing mail, and a spam flag can lock your personal mailbox. A custom-domain "Send mail as" address is signed with DKIM as gmail.com, so it does not align with DMARC for your domain.
- **Google Workspace (paid):** your own domain with aligned DKIM, and limits of about 2,000 per day per user. It is still a mailbox, not bulk sending infrastructure.

### Zoho Mail

Supports custom domains. SMTP host `smtp.zoho.com` (region-specific hosts exist). SMTP and IMAP access depends on the plan, so check your plan before connecting. For app mail, Zoho's transactional service (ZeptoMail) is a better fit and has its own adapter.

### Other mailboxes and relays

Fastmail, Proton (through Bridge), Postfix or your ISP's relay: anything that accepts SMTP AUTH works as a connection.

## Mailboxes compared with email APIs

Mailboxes are designed for people rather than applications. They have small daily limits, no bounce or complaint processing, no webhooks, no suppression or unsubscribe handling and no analytics, and their terms usually prohibit bulk sending. Put SMTP mailboxes at the end of your routing policy as a low-volume fallback and send most mail through email APIs.
