Send Email in Python via SMTP (smtplib)

Send emails through AhaSend’s SMTP servers using Python’s built-in smtplib and email modules. This guide covers everything from basic setup to advanced features like HTML content, attachments, and custom headers.

Prerequisites

Before sending, verify your domain and create an SMTP credential. Use a sandbox credential for these examples so no email is delivered. Keep the username and password in your server’s secret store. Before you begin, ensure you have:

System Requirements

Python installed on your system (Download Python)
a supported Python 3 release (recommended)
Basic knowledge of Python programming

Built-in Modules

Python’s standard library includes everything you need for SMTP:

smtplib Module

Purpose: SMTP client session object
Features: Connection, authentication, sending
Security: STARTTLS support
Import: import smtplib

email Module

Purpose: Email message construction
Features: MIME, attachments, HTML
Classes: EmailMessage, MIMEMultipart
Import: from email.message import EmailMessage

Connection Settings

Setting	Value
EU host	`send.ahasend.com`
US connection point	`send-us.ahasend.com`; accepts SMTP and forwards it to the EU
Ports	25, 587 and 2525
Encryption	STARTTLS required on every supported port
Authentication	AUTH PLAIN only after STARTTLS
Username and password	Your SMTP credential, not an API key
Port 465	Implicit TLS is not supported

All message data is stored in the EU. See SMTP limits.

Basic Email Examples

import smtplib
from email.message import EmailMessage

def send_plain_text_email():
    # SMTP server configuration
    smtp_server = "send.ahasend.com"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"

    # Email details
    from_addr = "hello@yourdomain.com"
    to_addr = "user@example.com"
    subject = "Welcome to our platform!"
    body = "Thanks for signing up. We're excited to have you!"

    # Create the email message
    msg = EmailMessage()
    msg.set_content(body)
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = to_addr

    # Connect to the SMTP server and send
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()  # Secure the connection
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("Email sent successfully!")
    except Exception as e:
        print(f"Failed to send email: {e}")

# Send the email
send_plain_text_email()

import smtplib
from email.message import EmailMessage

def send_html_email():
    # SMTP server configuration
    smtp_server = "send.ahasend.com"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"

    # Email details
    from_addr = "hello@yourdomain.com"
    to_addr = "user@example.com"
    subject = "Welcome to our platform!"

    # Create the email message
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = to_addr

    # Set plain text content (fallback)
    msg.set_content("Welcome! Thanks for signing up. Visit https://yourdomain.com/get-started to get started.")

    # Add HTML alternative
    html_content = """
    <html>
    <body>
        <h1>Welcome!</h1>
        <p>Thanks for signing up. We're <strong>excited</strong> to have you!</p>
        <p><a href="https://yourdomain.com/get-started">Get Started</a></p>
    </body>
    </html>
    """
    msg.add_alternative(html_content, subtype='html')

    # Connect and send
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("HTML email sent successfully!")
    except Exception as e:
        print(f"Failed to send email: {e}")

send_html_email()

import smtplib
from email.message import EmailMessage

def send_email_with_attachment():
    # SMTP server configuration
    smtp_server = "send.ahasend.com"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"

    # Email details
    from_addr = "hello@yourdomain.com"
    to_addr = "user@example.com"
    subject = "Your Invoice is Ready"

    # Create the email message
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = to_addr

    # Set content
    msg.set_content("Please find your invoice attached to this email.")

    # Add HTML alternative
    html_content = """
    <html>
    <body>
        <h1>Invoice Attached</h1>
        <p>Please find your invoice attached to this email.</p>
    </body>
    </html>
    """
    msg.add_alternative(html_content, subtype='html')

    # Add attachment
    attachment_path = "/path/to/invoice.pdf"
    try:
        with open(attachment_path, 'rb') as f:
            file_data = f.read()
            file_name = f.name.split('/')[-1]  # Get filename
            msg.add_attachment(file_data,
                             maintype='application',
                             subtype='pdf',
                             filename=file_name)
    except FileNotFoundError:
        print(f"Attachment file not found: {attachment_path}")
        return

    # Connect and send
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("Email with attachment sent successfully!")
    except Exception as e:
        print(f"Failed to send email: {e}")

send_email_with_attachment()

Pro Tip: Python’s built-in modules are powerful and reliable. Use context managers for connection handling, always provide both HTML and text versions, and implement proper error handling with retry logic. Start with sandbox mode during development and use environment variables for credentials.

Testing with Sandbox Mode

Use sandbox mode to safely test your Python email integration:

import smtplib
from email.message import EmailMessage

def send_sandbox_email():
    # SMTP server configuration
    smtp_server = "send.ahasend.com"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"

    # Email details
    from_addr = "test@yourdomain.com"
    to_addr = "test@example.com"
    subject = "Sandbox Test Email"

    # Create the email message
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = to_addr

    # Enable sandbox mode
    msg['AhaSend-Sandbox'] = 'true'
    msg['AhaSend-Sandbox-Result'] = 'deliver'

    msg.set_content("This email is sent in sandbox mode for testing.")

    # Connect and send
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("Sandbox email sent successfully!")
    except Exception as e:
        print(f"Failed to send sandbox email: {e}")

send_sandbox_email()

import smtplib
from email.message import EmailMessage

def send_sandbox_bounce_test():
    # SMTP server configuration
    smtp_server = "send.ahasend.com"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"

    # Email details
    from_addr = "test@yourdomain.com"
    to_addr = "test@example.com"
    subject = "Sandbox Bounce Test"

    # Create the email message
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = to_addr

    # Enable sandbox mode with bounce simulation
    msg['AhaSend-Sandbox'] = 'true'
    msg['AhaSend-Sandbox-Result'] = 'bounce'

    # Set content
    msg.set_content("This email simulates a bounce for webhook testing.")

    # Add HTML content
    html_content = """
    <html>
    <body>
        <h1>Bounce Test</h1>
        <p>This email simulates a bounce for webhook testing.</p>
    </body>
    </html>
    """
    msg.add_alternative(html_content, subtype='html')

    # Connect and send
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("Sandbox bounce test sent - check webhooks!")
    except Exception as e:
        print(f"Failed to send sandbox email: {e}")

send_sandbox_bounce_test()

import smtplib
from email.message import EmailMessage

def send_email_with_special_headers():
    # SMTP server configuration
    smtp_server = "send.ahasend.com"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"

    # Email details
    from_addr = "updates@yourdomain.com"
    to_addrs = ["user1@example.com", "user2@example.com"]
    subject = "Product Update with Tracking"

    # Create the email message
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = ", ".join(to_addrs)

    # Add AhaSend special headers
    msg['ahasend-track-opens'] = 'true'
    msg['ahasend-track-clicks'] = 'true'
    msg['ahasend-tags'] = 'product-update,newsletter,python'
    msg['AhaSend-Metadata-Retention'] = '30'
    msg['AhaSend-Data-Retention'] = '7'

    # Set content
    msg.set_content("Check out our latest features at https://yourdomain.com/features")

    # Add HTML content
    html_content = """
    <html>
    <body>
        <h1>Product Updates</h1>
        <p>Check out our <a href="https://yourdomain.com/features">latest features</a>!</p>
        <p>This email has tracking enabled and custom tags.</p>
    </body>
    </html>
    """
    msg.add_alternative(html_content, subtype='html')

    # Connect and send
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("Email sent with special headers!")
    except Exception as e:
        print(f"Failed to send email: {e}")

send_email_with_special_headers()

Sandbox Benefits: Emails sent in sandbox mode are free, trigger webhooks normally, and never actually deliver to recipients - perfect for development and testing.

Environment Variables & Best Practices

Using Environment Variables

smtplib with environment variables

import smtplib
import os
from email.message import EmailMessage

def send_email_with_env_vars():
    # Load configuration from environment variables
    smtp_server = os.getenv('SMTP_HOST', 'send.ahasend.com')
    smtp_port = int(os.getenv('SMTP_PORT', '587'))
    smtp_username = os.getenv('SMTP_USERNAME')
    smtp_password = os.getenv('SMTP_PASSWORD')
    from_email = os.getenv('FROM_EMAIL')
    from_name = os.getenv('FROM_NAME', 'Your Company')

    # Validate required environment variables
    required_vars = [smtp_username, smtp_password, from_email]
    if not all(required_vars):
        print("Missing required environment variables:")
        print("Set: SMTP_USERNAME, SMTP_PASSWORD, FROM_EMAIL")
        return False

    # Create email message
    msg = EmailMessage()
    msg['Subject'] = "Environment Variables Test"
    msg['From'] = f'"{from_name}" <{from_email}>'
    msg['To'] = "user@example.com"
    msg.set_content("This email uses environment variables for configuration.")

    # Send email
    try:
        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(smtp_username, smtp_password)
            server.send_message(msg)

        print("Email sent using environment variables!")
        return True
    except Exception as e:
        print(f"Failed to send email: {e}")
        return False

# Usage
if __name__ == "__main__":
    send_email_with_env_vars()

Resources

Python smtplib Documentation

Official Python smtplib module documentation

Python email Documentation

Official Python email module documentation

Python.org

Official Python programming language documentation

AhaSend Support

Get help from our engineering team

For framework setup, use Django or Flask. Python API guides cover AWS Lambda, Azure Functions and Cloud Run functions.

Before sending: verify your domain and create an SMTP credential.
Connection and message rules: SMTP hosts, ports and limits, special headers, sandbox mode, retention and plan features.
Other ways to send: REST API, AhaSend CLI, Node.js SDK and Go SDK.
Delivery events: webhook setup and local webhook testing.

Getting Started

Domain Authentication

Delivery and Troubleshooting

Sending with SMTP

Sending with the API

Email Tracking

Integrations

Data Retention

Security

Scaling up

Send Email in Python via SMTP (smtplib)

Prerequisites

Built-in Modules

smtplib Module

email Module

Connection Settings

Basic Email Examples

Testing with Sandbox Mode

Environment Variables & Best Practices

Using Environment Variables

Resources

Python smtplib Documentation

Python email Documentation

Python.org

AhaSend Support

​Prerequisites

​Built-in Modules

smtplib Module

email Module

​Connection Settings

​Basic Email Examples

​Testing with Sandbox Mode

​Environment Variables & Best Practices

​Using Environment Variables

​Resources

Python smtplib Documentation

Python email Documentation

Python.org

AhaSend Support

​Related Guides

Prerequisites

Built-in Modules

Connection Settings

Basic Email Examples

Testing with Sandbox Mode

Environment Variables & Best Practices

Using Environment Variables

Resources

Related Guides