Sign in to fill these examples with your own keys. Sign in Start free trial

Send emails with SMTP

STARTTLS on port 587 with AUTH PLAIN.

What you'll build

One test message sent over SMTP with swaks. Any SMTP client or framework mailer works with the same settings.

Before you start

  • An SMTP username and password. Open your cluster in the dashboard, go to its SMTP credentials, and choose Create SMTP credential. Copy the password right away, because it is shown once. You can also use the SMTP credentials API with a Full access key.
  • A verified sending domain. See Add and verify a domain.
  • A cluster that is ready to send (sending_ready is true). See Clusters.

SMTP settings

Setting Value
Host smtp.postshiba.com
Port 587
Encryption STARTTLS. Port 465 and implicit TLS are not offered.
Authentication AUTH PLAIN after STARTTLS. AUTH LOGIN fails.
Username The username you issued. It starts with smtp_.
Password The password shown when you issued the credential.
Message size 25 MB or less.

The envelope sender (MAIL FROM) and the From header must both use a verified domain.

Install

Install swaks to send a test from your terminal.

install.sh
1brew install swaks # macOS 2sudo apt install swaks # Debian and Ubuntu

Send your first email

Replace YOUR_PASSWORD with the password you copied.

send.sh
1swaks --server smtp.postshiba.com:587 --tls \ 2 --auth PLAIN --auth-user smtp_9 --auth-password YOUR_PASSWORD \ 3 --from hello@mail.example.com --to you@example.com \ 4 --header "Subject: Your receipt" \ 5 --header 'X-Capsule-Unique-Args: {"order_id":"ord_123"}' \ 6 --body "Thanks for your order."

The server replies 250 to DATA once the message is queued. The message then shows under Events in the dashboard.

X-Capsule-Unique-Args is optional. PostShiba strips it from the sent mail and returns its keys on every delivery webhook. See Unique args.

Attachments

SMTP takes standard multipart MIME. Attachments are delivered as sent, and the whole message must be 25 MB or less.

send-attachment.sh
1swaks --server smtp.postshiba.com:587 --tls \ 2 --auth PLAIN --auth-user smtp_9 --auth-password YOUR_PASSWORD \ 3 --from hello@mail.example.com --to you@example.com \ 4 --header "Subject: Your receipt" \ 5 --body "See attached." \ 6 --attach-name note.txt \ 7 --attach-type text/plain \ 8 --attach-body "hello"

Hosted templates work on the REST API, not over SMTP. See Send with a template.

Troubleshooting

When the cluster reaches its hourly throttle or 24-hour cap, SMTP answers 451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached and does not keep the message. Retry once the cap has room. See What happens at your cap.

What you see What to do
AUTH is rejected Check the username and password, and use AUTH PLAIN, not AUTH LOGIN.
454 4.7.0 too many failed logins, try again later Too many wrong passwords in the last minute. Fix the password. The right password still logs in.
530 5.7.0 Authentication required The client sent MAIL FROM without logging in. Turn on authentication and log in with AUTH PLAIN after STARTTLS.
550 unverified domain The MAIL FROM domain is not verified on this tenant. Finish Add and verify a domain.
550 from header not aligned with verified domain The From header uses a different domain. Use an address on your verified domain.
550 domain_suspended The From domain is paused. Resume it from Managing domains.
550 kyc_required Your team is pending production approval. Until then, send only to team members, live inbox addresses, and inbox forward-to addresses.
550 suppressed or 550 firewall: <rule> A recipient is on the suppression list or failed an email firewall check.
451 4.4.5 too many sessions, slow down Too many new sessions on one username. Reuse connections and send several messages per session.
451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached The cluster is at its cap. Retry later, or raise the cap. See What happens at your cap.

Next steps