Python smtplib SMTP setup for transactional email

Python's standard library sends transactional email through Viesti with no extra packages: build the message with email.message.EmailMessage and submit it with smtplib over STARTTLS on port 587.

Before you start

Sign in and verify the domain you send from. Viesti accepts a message only when its From address is on a domain verified in your workspace and the envelope sender (MAIL FROM), which most libraries take from the From address, is on the same domain. DNS setup lists the records.
Create an API key on the Credentials page of the dashboard. It is shown once. The key is the SMTP password; the username is apikey.

Setting	Value
Host	`smtp.viesti.email`
Port	`587` with STARTTLS, or `465` with TLS from the first byte
Username	`apikey`
Password	Your API key: `mr_` followed by 64 hex characters
Authentication	PLAIN, offered only once the connection is encrypted

Set the environment

export VIESTI_API_KEY="mr_your_api_key"
export MAIL_FROM="Acme <[email protected]>"

Send an email

Save this as send.py. Tested with Python 3.14.

import os
import smtplib
import ssl
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = os.environ["MAIL_FROM"]
msg["To"] = "[email protected]"
msg["Subject"] = "Your receipt"
msg.set_content("Thanks for your order.")
msg.add_alternative("<p>Thanks for your order.</p>", subtype="html")

context = ssl.create_default_context()
with smtplib.SMTP("smtp.viesti.email", 587, timeout=30) as smtp:
    smtp.starttls(context=context)
    smtp.login("apikey", os.environ["VIESTI_API_KEY"])
    smtp.send_message(msg)
print("Accepted")

starttls() must come before login(): Viesti offers authentication only on an encrypted connection. ssl.create_default_context() verifies the certificate and the host name. Without timeout, a blocked port can hang the call indefinitely.

Test it

python3 send.py

send_message() raises an exception when Viesti refuses the message, so reaching Accepted means it was taken. If only some of several recipients are refused, it returns them in a dictionary instead of raising. Follow the message on the Activity page of the dashboard.

Port 465

On 465 TLS starts before the SMTP greeting, so use SMTP_SSL and drop starttls():

context = ssl.create_default_context()
with smtplib.SMTP_SSL("smtp.viesti.email", 465, context=context, timeout=30) as smtp:
    smtp.login("apikey", os.environ["VIESTI_API_KEY"])
    smtp.send_message(msg)

Common errors

Error	Cause and fix
`smtplib.SMTPNotSupportedError: SMTP AUTH extension not supported by server.`	`login()` ran before `starttls()`, so the server had not offered AUTH yet. Call `starttls()` first.
`ssl.SSLError: [SSL: WRONG_VERSION_NUMBER] wrong version number`	`SMTP_SSL` on port 587. Use `SMTP` with `starttls()` on 587, `SMTP_SSL` on 465.
`smtplib.SMTPServerDisconnected: Connection unexpectedly closed: timed out`	`SMTP` on port 465: the server waits for a TLS handshake. Use `SMTP_SSL` for 465.
`smtplib.SMTPAuthenticationError: (535, b'5.7.8 Authentication failed')`	The key is wrong or revoked. Check `VIESTI_API_KEY` for stray whitespace or quotes.
`smtplib.SMTPDataError: (550, b'5.0.0 sending not permitted')`	The From address is not on a domain verified in your workspace.

Replies from Viesti

Whatever the library, its error includes the server's reply. These are the ones caused by your setup or account:

Reply	Meaning
`535 5.7.8 Authentication failed`	The API key is wrong, revoked or empty. After ten failed attempts from one client address within ten minutes, that address is refused for ten minutes with `454 Too many failed authentications; retry later`.
`525 5.7.13 Workspace suspended; contact support`	The key is valid, but the workspace is suspended or under review. Write to [email protected]; a new key does not help.
`550 5.0.0 sending not permitted`	The From domain is not verified in this workspace, the envelope sender is on a different domain than the From header, or the workspace is not active.
`550 5.0.0 recipient suppressed`	The recipient is on your suppression list after a bounce or complaint; see Bounces.
`451 4.0.0 submission quota exceeded`	The free plan's 75 emails per UTC day or 2,000 per UTC month are used up; see Limits. It is temporary: retry after the reset or upgrade.
`452 4.5.3 Maximum limit of 50 recipients reached`	One message can have at most 50 recipients. Split the send.
`552 5.0.0 message too large`	The message, attachments included, is over 10 MB.
`554 5.0.0 rejected by content audit`	Content screening found the message in violation of the Terms of Service. It is not relayed.

A 250 reply means Viesti accepted the message. Content screening runs before relay; mail it flags is held for review and shows as quarantined on the Activity page.

Next steps

DNS setup: DKIM, SPF, DMARC and return-path records for your domain.
SMTP reference: ports, TLS and authentication in detail.
HTTP API: send the same message as JSON over HTTPS.
Limits and Bounces: quotas, message size and suppressions.

API details are from the Python smtplib documentation. Checked 26 September 2026.