The fundamental mechanism for transferring mail is the Simple Mail Transfer Protocol, or SMTP. It is a text-based protocol, which means you can, in principle, telnet to port 25 on a mail server and type the commands yourself. Python’s standard library provides the smtplib module to abstract this process, but it is critical to understand the underlying dialog. The library handles the socket connection and command encoding, but you’re still driving the state machine of an SMTP session.
Let’s establish a connection. You instantiate an SMTP object, providing the host and port. For a standard unencrypted connection, this is typically port 25. For a connection that starts unencrypted and is then upgraded to TLS, it is often port 587. For a connection that’s encrypted from the outset with SSL/TLS, port 465 is the standard. An SMTP_SSL class exists for the latter case.
Here’s the initial connection. The debuglevel=1 argument is invaluable, as it prints the entire SMTP conversation to the console.
import smtplib
import getpass
# Using a public test server for demonstration
SMTP_SERVER = "smtp.mailtrap.io"
SMTP_PORT = 587 # Port for STARTTLS
SMTP_USER = "your_username" # Replace with your credentials
SMTP_PASSWORD = getpass.getpass("Enter password: ")
# The debuglevel=1 will print the entire SMTP conversation.
server = smtplib.SMTP(SMTP_SERVER, SMTP_PORT)
server.set_debuglevel(1)
After the TCP connection is established, the server sends a 220 Ready banner. The client must then identify itself. The modern command is EHLO (Extended HELO), which signals to the server that the client can handle SMTP service extensions. The older HELO is still supported for backward compatibility. smtplib handles this for you with the ehlo() method.
# The server responds with a 220 code. Now we send EHLO. server.ehlo()
The server responds with a 250 code for each extension it supports, such as STARTTLS, AUTH, and 8BITMIME. The most important one for modern email is STARTTLS. You must not send authentication credentials over an unencrypted channel. The starttls() method negotiates a TLS session over the existing connection. After this command, all subsequent communication is encrypted.
# If the server supports it, upgrade the connection to TLS. server.starttls() # You must call ehlo() again after STARTTLS. # The server's capabilities might change after encryption is enabled. server.ehlo()
With the channel secured, you can now authenticate. The login() method sends the AUTH LOGIN command, followed by the base64-encoded username and password. smtplib manages the encoding for you.
server.login(SMTP_USER, SMTP_PASSWORD)
The server should respond with a 235 Authentication Succeeded. Now the session is ready to transmit a message. The process involves three commands: MAIL FROM, RCPT TO, and DATA. The MAIL FROM command specifies the sender’s email address, which establishes the return path. The RCPT TO command specifies the recipient. You can call rcpt() multiple times for multiple recipients. Both commands should be acknowledged by the server with a 250 OK.
Finally, the DATA command signals that you are about to send the message content. The server responds with a 354 Go ahead. You then send the entire email message, including headers and body, as a single string. The end of the message is signaled by a line containing only a period (.).
Let’s construct a minimal message and send it using the low-level sendmail() method. This method takes the from address, a list of recipient addresses, and the full message string as arguments. It wraps the MAIL FROM, RCPT TO, and DATA sequence.
from_addr = "[email protected]" to_addr = "[email protected]" # The message must be a string. It must include the required headers. # Headers are separated from the body by a blank line (nn). message = """ From: Sender Name <[email protected]> To: Recipient Name <[email protected]> Subject: SMTP Low-Level Test That's the body of the test email. Sent via a raw SMTP dialog. """ server.sendmail(from_addr, to_addr, message)
After the final . is sent, the server processes the message and, if successful, responds with a 250 Queued for delivery. The last step is to terminate the session gracefully using the QUIT command, which is handled by the quit() method.
server.quit()
This entire sequence exposes the raw state transitions of SMTP. While sendmail() abstracts the core mail transaction, you are still manually managing the connection, encryption, and authentication steps. This level of control is necessary when dealing with non-standard server configurations or for deep debugging, but it is also error-prone. The message string itself has strict formatting requirements defined by RFC 5322. The headers like From, To, and Subject are not SMTP commands; they’re part of the data payload sent after the DATA command. The SMTP server itself doesn’t typically parse these headers to route the mail; it uses the envelope sender and recipients provided in the MAIL FROM and RCPT TO commands. The headers are for the recipient’s mail client. This distinction between the SMTP envelope and the message headers is a frequent point of confusion. A mismatch can lead to mail being rejected or flagged as spam. The raw string construction is brittle; a missing newline between headers and body will break parsing on the client side. That’s why for anything beyond simple text messages, you must move to a higher level of abstraction for message construction. The next logical step is to build properly formatted MIME messages, which handle character encodings, attachments, and alternative content types like HTML. This requires a different set of tools that work on top of the SMTP transport layer we’ve just examined. The raw message string we used is technically a MIME message, but of the simplest possible type: text/plain with an assumed ASCII character set. Any non-ASCII characters in that string would likely be garbled on receipt, as we haven’t specified a Content-Type header with a charset parameter.
MIME Message Construction and Payload Encoding
The limitations of raw string manipulation for message bodies become untenable for anything beyond basic ASCII text. The Multipurpose Internet Mail Extensions (MIME) standard addresses this by defining a structure for email messages that can contain multiple parts, non-textual content, and character set information. Python’s standard library provides the email package, a comprehensive toolset for building and parsing these complex structures. You move from concatenating strings to composing message objects.
The most basic object is MIMEText. It represents a block of text with a specific subtype (like plain or html) and a character set. This immediately solves the encoding problem. Instead of hoping the receiving client correctly guesses your character encoding, you declare it explicitly.
from email.mime.text import MIMEText # The text can contain non-ASCII characters. body = "This is a test message in UTF-8. Voilà!" # Create a MIMEText object. Specify the subtype 'plain' and encoding 'utf-8'. msg = MIMEText(body, 'plain', 'utf-8') # Headers are added as key-value pairs, like a dictionary. # The email package handles the correct formatting. msg['Subject'] = 'MIME Text Message Test' msg['From'] = '[email protected]' msg['To'] = '[email protected]' # To send this, you convert the object to a string. # This string is what you pass to smtplib's sendmail() method. message_string = msg.as_string() # print(message_string) # This would output a correctly formatted message string with # headers like: # Content-Type: text/plain; charset="utf-8" # Content-Transfer-Encoding: 8bit # MIME-Version: 1.0
The real power of MIME is in multipart messages. A common requirement is to send both plain text and HTML versions of an email in a single message. The client can then choose to display the richest format it supports. That’s accomplished with a MIMEMultipart object with the subtype 'alternative'. You create individual MIMEText objects for the plain and HTML parts and then attach them to the multipart container. The order of attachment is critical: clients are expected to use the last part they can understand, so you should attach the simplest format (plain text) first, followed by the more complex one (HTML).
from email.mime.multipart import MIMEMultipart
# Create the root container.
msg_root = MIMEMultipart('alternative')
msg_root['Subject'] = 'HTML and Plain Text Test'
msg_root['From'] = '[email protected]'
msg_root['To'] = '[email protected]'
# Plain text part.
text_part = MIMEText("This is the plain text version.", 'plain', 'utf-8')
# HTML part.
html_part = MIMEText(
"<html><body><p>This is the <b>HTML</b> version.</p></body></html>",
'html',
'utf-8'
)
# Attach parts to the root container. Plain text first.
msg_root.attach(text_part)
msg_root.attach(html_part)
# The final message string is generated from the root container.
message_string = msg_root.as_string()
Attachments require another layer of construction. Any non-textual data, like an image or a PDF, must be encoded into a text-safe format before it can be transmitted over SMTP. The standard encoding for that’s Base64. The file’s payload is also wrapped in a MIME part, typically of a generic type like application/octet-stream. The MIMEBase class is the foundation for this.
To combine a message body with an attachment, you use a MIMEMultipart('mixed') container. This container holds the main body of the message (which itself could be a MIMEMultipart('alternative') object) and the various attachment parts. For each attachment, you must also add a Content-Disposition header. This header tells the mail client how to treat the part; the value 'attachment' with a filename parameter suggests it should be presented to the user as a downloadable file.
Let’s construct a message with an alternative text/HTML body and a binary attachment. This requires a nested structure: a root MIMEMultipart('mixed') that contains a MIMEMultipart('alternative') and a MIMEBase part for the attachment.
from email.mime.base import MIMEBase
from email import encoders
# Assume the previous 'alternative' message (msg_root) is already created.
# Create a new top-level container for message body + attachment.
msg_container = MIMEMultipart('mixed')
msg_container['Subject'] = 'Message with Attachment'
msg_container['From'] = '[email protected]'
msg_container['To'] = '[email protected]'
# Attach the alternative text/html body to the mixed container.
# Note: We are attaching the entire MIMEMultipart('alternative') object.
msg_container.attach(msg_root)
# Create the attachment part.
# For demonstration, we'll create a dummy binary file in memory.
# In a real application, you would open a file with 'rb'.
# with open('document.pdf', 'rb') as f:
# file_data = f.read()
# filename = 'document.pdf'
file_data = b'x00x01x02x03x04x05'
filename = 'data.bin'
# Create a generic binary MIME part.
attachment_part = MIMEBase('application', 'octet-stream')
attachment_part.set_payload(file_data)
# SMTP servers are often 7-bit, so binary data must be encoded.
# Base64 is the standard for this.
encoders.encode_base64(attachment_part)
# Add the header to tell the client that is an attachment.
attachment_part.add_header(
'Content-Disposition',
f'attachment; filename="{filename}"',
)
# Attach the attachment part to the mixed container.
msg_container.attach(attachment_part)
# The final string is now generated from the outermost container.
# This string contains all parts, correctly structured and encoded.
final_message_string = msg_container.as_string()
This object-oriented construction is far more robust than string manipulation. The email package correctly handles the complexities of MIME boundaries, content type declarations, and payload encodings. The resulting final_message_string is the payload you provide to the smtplib.sendmail() function. The SMTP layer remains agnostic to the content; its job is simply to transport this block of text, which the recipient’s mail client will then parse according to MIME rules. This separation of concerns—message construction versus message transport—is a core design principle of the system.
