How To Send Emails with Python Using smtplib and Gmail

All systems operational. Have a great week!

Output:

HTML email sent!

The key method here is msg.add_alternative(html_content, subtype="html"). This tells the email that it has two versions: the plain text you set with set_content() and the HTML alternative. Always provide both -- some email clients strip HTML entirely, and a plain-text fallback ensures your message is readable everywhere.

Adding File Attachments

Sending reports, logs, or CSV files as email attachments is a common automation task. The EmailMessage class handles this with add_attachment(), which automatically detects the file type and encodes it correctly.

# attachment_email.py
import smtplib
import os
import mimetypes
from email.message import EmailMessage
from pathlib import Path

def send_email_with_attachment(to_address, subject, body, file_path):
    """Send an email with a file attachment."""
    msg = EmailMessage()
    msg["Subject"] = subject
    msg["From"] = os.environ["GMAIL_ADDRESS"]
    msg["To"] = to_address
    msg.set_content(body)

    # Read and attach the file
    filepath = Path(file_path)
    if not filepath.exists():
        raise FileNotFoundError(f"Attachment not found: {file_path}")

    mime_type, _ = mimetypes.guess_type(str(filepath))
    if mime_type is None:
        mime_type = "application/octet-stream"
    maintype, subtype = mime_type.split("/")

    with open(filepath, "rb") as f:
        msg.add_attachment(
            f.read(),
            maintype=maintype,
            subtype=subtype,
            filename=filepath.name
        )

    with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
        server.login(os.environ["GMAIL_ADDRESS"], os.environ["GMAIL_APP_PASSWORD"])
        server.send_message(msg)

    print(f"Email sent to {to_address} with attachment: {filepath.name}")


# Create a sample CSV file for testing
sample_csv = "name,score,grade\nAlice,95,A\nBob,87,B\nCharlie,72,C\n"
Path("report.csv").write_text(sample_csv)

# Send it
send_email_with_attachment(
    to_address=os.environ["GMAIL_ADDRESS"],
    subject="Monthly Report Attached",
    body="Please find the monthly report attached to this email.",
    file_path="report.csv"
)

Output:

Email sent to your_email@gmail.com with attachment: report.csv

The mimetypes.guess_type() function automatically detects the correct MIME type from the file extension -- text/csv for CSV files, application/pdf for PDFs, image/png for images, and so on. If the type cannot be determined, we fall back to application/octet-stream which tells the email client to treat it as a generic binary file. You can attach multiple files by calling add_attachment() multiple times on the same message.

Sending to Multiple Recipients

Often you need to send the same email to several people -- maybe a team notification or a batch of personalized messages. There are two approaches: sending one email to multiple recipients (everyone sees all addresses) or sending individual emails (each person sees only their address).

# multiple_recipients.py
import smtplib
import os
from email.message import EmailMessage

def send_to_group(recipients, subject, body)
   """Send one email to multiple recipients (all visible in To field)."""
    msg = EmailMessage()
    msg["Subject"] = subject
    msg["From"] = os.environ["GMAIL_ADDRESS"]
    msg["To"] = ", ".join(recipients)
    msg.set_content(body)

    with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
        server.login(os.environ["GMAIL_ADDRESS"], os.environ["GMAIL_APP_PASSWORD"])
        server.send_message(msg)

    print(f"Group email sent to {len(recipients)} recipients")


def send_individual(recipients, subject_template, body_template):
    """Send personalized emails to each recipient individualy."""
    with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
        server.login(os.environ["GMAIL_ADDRESS"], os.environ["GMAIL_APP_PASSWORD"])

        for name, email_addr in recipients:
            msg = EmailMessage()
            msg["Subject"] = subject_template.format(name=name)
            msg["From"] = os.environ["GMAIL_ADDRESS"]
            msg["To"] = email_addr
            msg.set_content(body_template.format(name=name))
            server.send_message(msg)
            print(f"Sent to {name} ({email_addr})")

    print(f"All {len(recipients)} individual emails sent!")


# Example: group email
team = ["alice@example.com", "bob@example.com", "charlie@example.com"]
send_to_group(team, "Team Update", "Sprint review meeting moved to 3 PM.")

# Example: personalized emails
contacts = [("Alice", "alice@example.com"), ("Bob", "bob@example.com")]
send_individual(
    contacts,
    subject_template="Hey {name}, your weekly summary",
    body_template="Hi {name},\n\nHere is your personalized weekly summary.\n\nBest regards"
)

Real-Life Example: Automated Error Alert System

Let us tie everything together with a practical project. This script monitors a log file for errors and sends an HTML alert email with a summary of any issues found. It combines plain text processing, HTML email formatting, and the EmailNotifier class pattern you can reuse in any project.

# Create a sample log file for demonstration
sample_log = """2026-03-31 08:00:01 INFO  Starting data pipeline
2026-03-31 08:00:05 INFO  Connected to database
2026-03-31 08:00:12 WARNING  Slow query detected (2.3s)
2026-03-31 08:00:15 ERROR  Failed to fetch API data: ConnectionTimeout
2026-03-31 08:00:16 ERROR  Retry 1 of 3 failed
2026-03-31 08:00:20 INFO  Retry 2 succeeded
2026-03-31 08:00:45 CRITICAL  Database connection lost
2026-03-31 08:00:46 INFO  Reconnecting to database...
2026-03-31 08:01:00 INFO  Pipeline completed with errors
"""
Path("app.log").write_text(sample_log)

# Check the log and send an alert if errors are found
def check_log_for_errors(log_path):
    """Scan a log file and return any lines containing ERROR or CRITICAL."""
    errors = []
    path = Path(log_path)
    if not path.exists():
        return errors

    with open(path, "r") as f:
        for line_num, line in enumerate(f, 1):
            stripped = line.strip()
            if "ERROR" in stripped or "CRITICAL" in stripped:
                errors.append({"line": line_num, "text": stripped})

    return errors


def build_alert_html(log_file, errors):
    """Build an HTML alert email from error entries."""
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    rows = ""
    for err in errors:
        rows += f'{err["line"]}'
        rows += f'{err["text"]}'

    return f"""""

sample_log = """2026-03-31 08:00:01 INFO  Starting data pipeline
2026-03-31 08:00:05 INFO  Connected to database
2026-03-31 08:00:12 WARNING  Slow query detected (2.3s)
2026-03-31 08:00:15 ERROR  Failed to fetch API data: ConnectionTimeout
2026-03-31 08:00:16 ERROR  Retry 1 of 3 failed
2026-03-31 08:00:20 INFO  Retry 2 succeeded
2026-03-31 08:00:45 CRITICAL  Database connection lost
2026-03-31 08:00:46 INFO  Reconnecting to database...
2026-03-31 08:01:00 INFO  Pipeline completed with errors
"""
Path("app.log").write_text(sample_log)

# Check the log and send an alert if errors are found
class EmailNotifier:
    """Reusable email notification system" HTML alert built {len(errors)} chars)
In production: notifier.send(admin_email, subject, body, html)
else:
    print("No errors found. All clear!")

Output:

Found 3 error(s) in app.log:
  Line 4: 2026-03-31 08:00:15 ERROR  Failed to fetch API data: ConnectionTimeout
  Line 5: 2026-03-31 08:00:16 ERROR  Retry 1 of 3 failed
  Line 7: 2026-03-31 08:00:45 CRITICAL  Database connection lost

HTML alert built (698 chars)
In production: notifier.send(admin_email, subject, body, html)

This notification system is designed to be dropped into any existing project. The EmailNotifier class handles all the SMTP details, check_log_for_errors() scans for problems, and build_alert_html() creates a readable alert email. You could schedule this to run every hour with cron or the schedule library, and you would have a lightweight monitoring system without any third-party services.

Gmail Sending Limits and Best Practices

Gmail enforces rate limits on how many emails you can send per day. Knowing these limits prevents your script from getting temporarily blocked.

If you hit these limits, Gmail returns an SMTPDataError with code 421 or 550. Your script should catch this and wait before retrying. For high-volume sending (marketing emails, large mailing lists), use a dedicated email service like SendGrid, Mailgun, or Amazon SES instead of Gmail -- they are designed for bulk sending and provide analytics, bounce handling, and higher limits.

Frequently Asked Questions

How do I create a Gmail App Password?

Go to myaccount.google.com/apppasswords after enabling 2-Step Verification on your account. Click "Select app," choose "Other," type a name like "Python Script," and click Generate. Copy the 16-character password and use it in your server.login() call instead of your regular Gmail password. You can revoke it anytime from the same page.

Why does Gmail reject my login with SMTPAuthenticationError?

This almost always means you are using your regular Gmail password instead of an App Password. Google disabled "Less Secure App Access" permanently in 2022. You must use an App Password (see the section above) or switch to OAuth2 for more complex applications. Double-check that there are no extra spaces in your password string.

My script hangs when connecting to the SMTP server. What is wrong?

Add a timeout parameter to your SMTP connection: smtplib.SMTP_SSL("smtp.gmail.com", 465, timeout=30). This prevents the script from hanging forever if the server is unreachable. Common causes include corporate firewalls blocking port 465 or 587, VPN interference, or DNS resolution failures. Try pinging smtp.gmail.com from your terminal to verify connectivity.

How do I send emails with special characters or non-English text?

The EmailMessage class handles Unicode correctly by default. Just pass your text normally: msg.set_content("Bonjour! Voici votre rapport."). The message will be encoded as UTF-8 automatically. If you are using the older MIMEText API, explicitly set the charset: MIMEText(body, "plain", "utf-8").

How can I test email sending without actually sending emails?

Python has a built-in debugging SMTP server that prints emails to the terminal instead of sending them. Run python -m smtpd -n -c DebuggingServer localhost:1025 in one terminal, then connect your script to localhost:1025 using smtplib.SMTP("localhost", 1025) (no SSL, no login). You will see the full email content printed to the terminal. For Python 3.12+, use aiosmtpd instead since the built-in smtpd module was removed.

Conclusion

You now have everything you need to send emails from Python scripts: plain text messages with set_content(), HTML-formatted emails with add_alternative(), file attachments with add_attachment(), and a robust error-handling wrapper with retry logic. The notification system project gives you a ready-to-use template for monitoring any automated task.

Try extending the notification system to watch multiple log files, send daily digest emails instead of per-error alerts, or add Slack webhook notifications alongside email. The EmailNotifier class is designed to be subclassed and customized for your specific needs.

For the complete API reference, see the official Python documentation for smtplib and email.message.

Related Articles

• How To Automate Tasks with Python: A Practical Guide
• How To Use Python Environment Variables with dotenv
• How To Work with JSON Files in Python