smtplib<\/code> module together with email.message.EmailMessage<\/code> to build and send a message over an authenticated SMTP connection:<\/p>\n\n\n\nimport smtplib\nfrom email.message import EmailMessage\n\nmsg = EmailMessage()\nmsg[\"Subject\"] = \"Your verification code\"\nmsg[\"From\"] = \"noreply@yourdomain.com\"\nmsg[\"To\"] = \"user@example.com\"\nmsg.set_content(\"Your code is 492019.\")\n\nwith smtplib.SMTP(\"smtp.photonconsole.com\", 587) as server:\n server.starttls()\n server.login(\"your_project_api_user\", \"your_secret_api_key\")\n server.send_message(msg)<\/code><\/pre>\n\n\n\nThe library ships with every Python install, so there is nothing to install. The part that determines whether this works in production is the host you connect to. An unauthenticated personal mailbox or an unverified server will fail under real traffic; an authenticated relay such as PhotonConsole<\/a> on port 587 with TLS is what keeps delivery working once you are past a handful of test emails.<\/p>\n\n\n\nWhat smtplib Actually Does<\/h2>\n\n\n\n
smtplib is Python’s built-in client for the SMTP protocol. It opens a socket, speaks the SMTP command sequence, and hands your message to a mail server. It does not compose messages, manage templates, track opens, or retry failures \u2014 that is what the email<\/code> package and your own application code are for.<\/p>\n\n\n\nThis matters because most “smtplib is broken” reports are actually one of two other things failing: the message wasn’t built to spec by the email<\/code> package, or the server on the other end rejected the connection. If you want the protocol fundamentals first, see our guide to what SMTP is<\/a>.<\/p>\n\n\n\nWhy smtplib Fails in Production<\/h2>\n\n\n\n
Most SMTP errors occur due to misconfiguration or authentication issues rather than defects in smtplib itself. These five causes account for the majority of Python email failures.<\/p>\n\n\n\n
1. Using SMTP() When the Server Requires SMTP_SSL()<\/h3>\n\n\n\n
Python’s smtplib documentation<\/a> is explicit that SMTP_SSL<\/code> is for connections that are encrypted from the first byte, typically port 465, while SMTP<\/code> combined with .starttls()<\/code> upgrades an initially plain connection, typically port 587. Using the wrong pairing produces a connection that hangs until it times out, with no useful error message.<\/p>\n\n\n\n2. Blocking Calls With No Timeout<\/h3>\n\n\n\n
By default, smtplib.SMTP()<\/code> will wait indefinitely for a response. A single slow or unresponsive server can freeze a request thread completely. Every production connection needs an explicit timeout<\/code> argument.<\/p>\n\n\n\n3. Your Host Blocks Outbound Port 25<\/h3>\n\n\n\n
AWS, Google Cloud, DigitalOcean and Azure all restrict outbound traffic on port 25 by default to control spam abuse. If your code targets port 25, the connection attempt stalls and eventually errors out. AWS documents its port 25 throttle removal process<\/a>, but removal does not solve the underlying reputation problem of sending from a fresh IP. Our guide to SMTP connection timeouts<\/a> covers the full diagnosis.<\/p>\n\n\n\n4. One Connection Per Email<\/h3>\n\n\n\n
Opening a new smtplib.SMTP<\/code> instance for every message forces a fresh TCP handshake and TLS negotiation each time. At any real volume this is slow, and it looks like abusive traffic to the receiving server, which starts throttling or blocking the connection.<\/p>\n\n\n\n5. No Authentication Records on the Sending Domain<\/h3>\n\n\n\n
Without SPF and DKIM configured, mailbox providers cannot confirm your server was authorised to send as your domain, and messages are filtered or rejected outright regardless of how correct your Python code is. This is covered fully in our guide to SPF, DKIM and DMARC<\/a>.<\/p>\n\n\n\nQuick Fix<\/p>\n\n\n\n
smtplib Hangs and Never Returns<\/p>\n\n\n\n
\n- Add an explicit
timeout=10<\/code> to your SMTP()<\/code> or SMTP_SSL()<\/code> call<\/li>\n\n\n\n- Confirm you are using port 587 with
.starttls()<\/code>, or port 465 with SMTP_SSL()<\/code> \u2014 never mix the two patterns<\/li>\n\n\n\n- Try port 2525 if your host silently blocks 587 and 465 outbound<\/li>\n\n\n\n
- Wrap the connection in a try\/except that catches
socket.timeout<\/code> specifically<\/li>\n\n\n\n- Confirm the host resolves with a DNS lookup before assuming the server is at fault<\/li>\n<\/ul>\n\n\n\n
Step-by-Step: Sending Email With smtplib<\/h2>\n\n\n\nStep 1: Build the Message With the email Package<\/h3>\n\n\n\n
Never hand-build raw SMTP message text. Use EmailMessage<\/code>, which handles headers, encoding and line-length rules correctly.<\/p>\n\n\n\nfrom email.message import EmailMessage\n\nmsg = EmailMessage()\nmsg[\"Subject\"] = \"Your order has shipped\"\nmsg[\"From\"] = \"orders@yourdomain.com\"\nmsg[\"To\"] = \"customer@example.com\"\nmsg.set_content(\"Your order #10928 has shipped.\")\n\n# Optional HTML alternative\nmsg.add_alternative(\n \"<p>Your order <strong>#10928<\/strong> has shipped.<\/p>\",\n subtype=\"html\"\n)<\/code><\/pre>\n\n\n\nStep 2: Store Credentials as Environment Variables<\/h3>\n\n\n\n
Never hardcode SMTP credentials in source. Read them from the environment and keep secrets out of version control.<\/p>\n\n\n\n
import os\n\nSMTP_HOST = os.environ[\"SMTP_HOST\"]\nSMTP_PORT = int(os.environ.get(\"SMTP_PORT\", 587))\nSMTP_USER = os.environ[\"SMTP_USER\"]\nSMTP_PASS = os.environ[\"SMTP_PASS\"]<\/code><\/pre>\n\n\n\nStep 3: Connect With an Explicit Timeout<\/h3>\n\n\n\nimport smtplib\n\ndef get_connection():\n server = smtplib.SMTP(SMTP_HOST, SMTP_PORT, timeout=10)\n server.starttls()\n server.login(SMTP_USER, SMTP_PASS)\n return server<\/code><\/pre>\n\n\n\nCommon Mistake<\/p>\n\n\n\n
Opening a fresh smtplib.SMTP<\/code> connection inside a loop or a per-request function is the single most common cause of slow, unreliable Python email sending. Every connection re-runs the TCP handshake and the TLS negotiation from zero. Open one connection, send everything you need through it, and close it \u2014 the pattern shown in Step 4.<\/p>\n\n\n\nStep 4: Reuse One Connection for Multiple Sends<\/h3>\n\n\n\n
If you are sending several messages in the same process, open the connection once and reuse it rather than reconnecting per message.<\/p>\n\n\n\n
def send_batch(messages):\n with smtplib.SMTP(SMTP_HOST, SMTP_PORT, timeout=10) as server:\n server.starttls()\n server.login(SMTP_USER, SMTP_PASS)\n for msg in messages:\n server.send_message(msg)<\/code><\/pre>\n\n\n\nStep 5: Handle Errors Explicitly<\/h3>\n\n\n\n
smtplib raises specific exceptions for specific failures. Catching the base Exception<\/code> class hides which one actually happened.<\/p>\n\n\n\nimport logging\n\ndef send_email(msg):\n try:\n with smtplib.SMTP(SMTP_HOST, SMTP_PORT, timeout=10) as server:\n server.starttls()\n server.login(SMTP_USER, SMTP_PASS)\n server.send_message(msg)\n return True\n except smtplib.SMTPAuthenticationError as e:\n logging.error(\"SMTP auth rejected: %s\", e)\n except smtplib.SMTPConnectError as e:\n logging.error(\"Could not connect to SMTP host: %s\", e)\n except smtplib.SMTPRecipientsRefused as e:\n logging.error(\"Recipient refused: %s\", e.recipients)\n except (TimeoutError, smtplib.SMTPServerDisconnected) as e:\n logging.error(\"Connection timed out or dropped: %s\", e)\n return False<\/code><\/pre>\n\n\n\nFor interpreting the numeric codes inside these exceptions, our reference on SMTP response codes<\/a> maps each one to its cause.<\/p>\n\n\n\nStep 6: Add Retry Logic for Transient Failures<\/h3>\n\n\n\n
A 4xx response is temporary; a 5xx response is permanent. Retrying a permanent failure wastes time and can damage your sender reputation.<\/p>\n\n\n\n
import time\n\ndef send_with_retry(msg, attempts=3):\n for i in range(attempts):\n try:\n return send_email(msg)\n except smtplib.SMTPResponseException as e:\n if 400 <= e.smtp_code < 500 and i < attempts - 1:\n time.sleep(2 ** i) # 1s, 2s, 4s\n continue\n raise<\/code><\/pre>\n\n\n\nFor a deeper treatment of backoff strategy across an entire sending pipeline, see our guide to SMTP retry logic for transactional systems<\/a>.<\/p>\n\n\n\nWhy smtplib Breaks Down at Scale<\/h2>\n\n\n\n![\"\"](\"https:\/\/photonconsole.com\/blog\/wp-content\/uploads\/2026\/09\/Blocking-vs-Queued-Sending-Infographic-1024x512.png\")
A direct smtplib call blocks the calling process until the full SMTP conversation completes.<\/figcaption><\/figure>\n\n\n\nsmtplib is synchronous and blocking by design. Each send_message()<\/code> call waits for the full SMTP conversation to complete before your code continues. That is fine for a script sending a handful of emails. It becomes the bottleneck once your application needs to send hundreds or thousands of messages without freezing the process that triggered them \u2014 regardless of which relay, including PhotonConsole, sits on the other end of the connection.<\/p>\n\n\n\n
![\"\"](\"https:\/\/photonconsole.com\/blog\/wp-content\/uploads\/2026\/09\/SMTP-vs-Email-API-Infographic-1024x512-1.png\")