Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

SMTP relay

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

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

Was this page helpful?