SMTP

Use SMTP when an app or platform only lets you enter an SMTP server. Every message you submit goes through the same checks, limits and email log as POST /mail/send. If your code can make an HTTPS request, the API is usually simpler: see Sending email.

Connection settings#

The same settings are shown in the dashboard under API keys (/app/forms/api-keys), in the SMTP settings box. Each site has its own key, so mail is logged and counted under the site whose key you log in with. Rotating the key stops SMTP logins with the old key at once. See Sites and API keys.

What happens to SMTP mail#

We read the message, turn it into an API request and run it through POST /mail/send. In the email log its source is smtp. That means SMTP mail gets:

• the per-site rate limit (120 emails per 60 seconds) and your plan’s monthly limit;
• the content check, the AI spam check and the contact-form spam hold — see Deliverability;
• suppression and unsubscribe checks — see Bounces and suppressions;
• open and click tracking, and the one-click unsubscribe header on single-recipient mail;
• webhook events after sending — see Webhooks.

You cannot choose the sender mode over SMTP. If the site has a verified sending domain, mail goes out from it; otherwise it goes out in relay mode.

From and Reply-To#

The address in your From header is never used as the From address. If your From header has no display name, we use the site’s default From name, then the site name. To send from your own address, verify a domain: see Domains and DNS.

Recipients and Bcc#

• To and Cc are taken from the message headers, but only addresses that are also envelope recipients (RCPT TO) are kept.
• Envelope recipients that are not in To or Cc are sent as Bcc.
• If the message has Cc addresses but no To, the Cc addresses become the To addresses.
• If the message has no visible recipients at all (everyone is Bcc), each recipient gets their own copy. Each copy is a separate email: it counts toward the limits and has its own line in the email log. The SMTP reply is 250 if at least one copy was accepted.
• Up to 50 addresses each in To, Cc and Bcc. A message can have up to 150 envelope recipients; further RCPT TO commands are refused.
• Suppression and unsubscribe checks apply to the To addresses only. Cc and Bcc addresses are not checked.

Headers we keep#

Most headers are rebuilt by us (From, Reply-To, Message-ID and so on). These headers from your message are passed through unchanged, up to 30 of them:

• X- headers, except X-Mailer, X-Originating-IP, X-PHP-Originating-Script, X-MS-Exchange-*, X-Google-*, X-GM-*, X-Received*, X-Spam* and X-Virus*;
• In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post, List-Id, Precedence and Auto-Submitted.

If your message has its own List-Unsubscribe header, we keep it and do not add ours. See Unsubscribe links.

Attachments and size#

• Attachments are sent, up to 15 MB in total per message.
• Inline images (an attachment with Content-Disposition: inline and a Content-ID) stay inline, so <img src="cid:..."> keeps working.
• The whole message, including encoded attachments, can be up to 25 MB.

SMTP replies#

Replies starting with 4 are temporary: a normal SMTP client keeps the message and tries again later. Replies starting with 5 are final: sending the same message again will fail the same way.

Examples#

All examples use port 587 with STARTTLS, the username securessmtp and the API key from the SECURESSMTP_API_KEY environment variable as the password.

swaks --server smtp.securessmtp.com --port 587 --tls \
  --auth LOGIN --auth-user securessmtp --auth-password "$SECURESSMTP_API_KEY" \
  --from [email protected] --to [email protected] \
  --header "Subject: Hello from SecureSMTP" \
  --body "It works."

For port 465, connect with TLS from the start: swaks --tlsc --port 465, smtplib.SMTP_SSL("smtp.securessmtp.com", 465) without starttls(), port: 465, secure: true in nodemailer, or PHPMailer::ENCRYPTION_SMTPS with port 465 in PHPMailer.

Framework settings: Django, Laravel, Ruby on Rails.

Troubleshooting#

535 when logging in

• Check that the password is the whole key, starts with qcs_live_ and has no spaces or line breaks.
• If the key was rotated, the old key stopped working at once. Use the new one.
• If the site was disabled, logins are refused. See Blocks.

The connection times out

Many hosting providers and cloud platforms block outgoing SMTP ports. Try the other port (465 instead of 587, or the other way round). If both are blocked, send with the REST API instead: it uses HTTPS on port 443. See Quickstart.

The client says the server does not support authentication

Login is only offered after TLS is on. Turn on STARTTLS for port 587, or SSL/TLS for port 465. A mismatch (SSL/TLS on 587, or STARTTLS on 465) usually shows up as a TLS handshake error or a timeout.

Recipients see a different From address

That is relay mode. Verify your domain to send from your own address: see Domains and DNS.

The message was accepted but did not arrive

Look it up in the email log. It shows whether the email was delivered, bounced or flagged, and why. Also check the suppression list.

450 4.7.0 during large sends

You sent more than 120 emails in 60 seconds from one site. Most SMTP clients retry on their own. If you send in bulk, slow down to stay under the limit.