SMTP relay guide
Send through the platform from any application or device that speaks SMTP: legacy apps, off-the-shelf software, printers and scanners, cron jobs. The relay accepts your message the way the REST API does (same streams, same policy, same delivery events) and answers with the message id you can follow in the panel or through the API. Your message is relayed as you built it: no link rewriting, no open pixel and no header injection happen on the SMTP path.
Endpoint
| Setting | Value |
|---|---|
| Host | smtp.<your platform domain> (the panel's Settings page shows the exact host) |
| Port 587 | STARTTLS: connect in plain text, issue STARTTLS, then authenticate |
| Port 465 | Implicit TLS: the connection starts with the TLS handshake |
| Port 25 | Closed |
| TLS | TLS 1.2 or newer with a public certificate; the server name is the host above |
| Authentication | AUTH PLAIN or AUTH LOGIN, only after TLS (an AUTH before STARTTLS answers 538) |
| Username and password | An SMTP credential created in the panel under SMTP credentials; one credential is bound to one stream |
What one credential can do
- The credential's stream decides the lane (transactional or broadcast) and the sending policy; the
Fromaddress must belong to a verified sending identity of your account, or the transaction answers550 5.7.1 the From header is not a sending identity of this account. - Up to 50 recipients per transaction (
RCPT TO); the 51st answers `452 4.5.3 too many
recipients`. Every recipient becomes its own message with its own id.
- Message size follows the API limit (the built message including attachments); a larger
DATAanswers552 5.3.4 message size exceeds the fixed maximum. - Rate: the per-minute budget of your plan (
send_rpstimes 60) per credential; over budget the transaction answers452 4.2.1 rate limit exceeded, try again later. Retry later, do not loop. - Headers you set are kept; the relay strips
Bccand adds its own transport headers (Received, DKIM). Unsafe or malformed headers answer550 5.6.0 message headers refused.
Replies to expect
| Reply | Meaning | What to do |
|---|---|---|
250 2.0.0 queued as msg_… msg_… | Accepted: one message id per recipient, in RCPT TO order | Store the ids; delivery, bounces and opens arrive as events and in the panel |
421 4.3.2 service not available (at the banner) | The product is paused or in maintenance | Retry later; nothing was accepted |
421 4.7.0 connection refused, try again later | Your IP is temporarily banned (see below) or over the connection rate | Wait; fix the client that loops |
535 5.7.8 authentication credentials invalid | Wrong username or password | Check the credential; it is bound to one stream |
535 5.7.8 too many failed authentication attempts, try again later | Lockout | Wait 15 minutes and fix the stored password |
550 5.7.1 rejected by policy | Admission refused the message (suppressed recipient, missing unsubscribe on a broadcast stream, quota) | Read the reason in the panel's message view or the API's reason_codes |
451 4.3.0 temporary failure, try again later | A transient platform error | Retry with backoff |
538 (before STARTTLS) | AUTH was attempted on a plain connection | Issue STARTTLS first, or use port 465 |
550 5.6.0 the credential binds no usable stream | The credential's stream is gone or unusable | Create a new credential in the panel |
550 5.6.0 message refused | The message could not be accepted as built | Check the From, the size and the headers |
Lockouts and bans
Five failed AUTH for one credential, or from one IP, within 15 minutes lock that credential or that IP for the rest of the window; twenty failures ban the source for one hour. A ban is lifted on request by support (the platform's unban action) after the client that produced the failures has been fixed. Use one credential per application so a leaked or rotated password affects one integration only, and rotate from the panel: the old password stops working as soon as the platform's credential index is updated.
Client settings that work
- Connection: 587 with STARTTLS or 465 with TLS; both need SNI (
smtp.<domain>). - Keep-alive: send a few messages per session and reconnect; the server closes idle sessions after 30 seconds without a command and a
DATAphase after 120 seconds. - Concurrency: at most 20 connections per source IP and 60 new connections per minute; a mail queue that opens a connection per message should pace itself or use the REST API's batch call.
- Envelope: the relay checks the
Fromheader (a sending identity of your account); the envelope sender is not checked and bounce handling is the platform's.
Tracking and unsubscribe
Messages relayed over SMTP are stored and sent as you built them: no open pixel, no link rewriting and no unsubscribe header are added (the stream's Track opens / Track clicks settings and its default unsubscribe URL apply to the REST API path only). Delivery, bounce and complaint events still arrive. A message on the broadcast lane must carry its own List-Unsubscribe header; a broadcast without one is refused by policy (550 5.7.1 rejected by policy).
Following a message
The message ids from the 250 reply work everywhere: GET /v1/emails/{message_id} and its events, the panel's message page (timeline, attempts, the built message for download), and the email.* webhook events (email.accepted.v1, email.sent.v1, email.delivered.v1, email.bounced.v1, ...). A quick test: send to success@simulator.amazonses.com (delivered) or bounce@simulator.amazonses.com (hard bounce) and watch the timeline; these addresses never reach a mailbox.