Docs / Sending and domains

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.

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.

SettingValue
HostYour OneSend host
Port2587 (ONESEND_SMTP_PORT)
SecuritySTARTTLS when TLS is configured (see TLS); without TLS, only clients on the same host can authenticate
UsernameAny value, for example onesend
PasswordA 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.

TLS

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

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.

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