yagmail

library0.16.0pypypi✓ verified 21d ago

yagmail (Yet Another GMAIL client) is a Python library designed to simplify sending emails, particularly with Gmail accounts, by abstracting away the complexities of SMTP, MIME, and headers. It is currently at version 0.15.293 and is actively maintained, with regular updates addressing features and compatibility.

communication

pip install yagmail[all]

github ↗package ↗

INSTALL

IMPORT

SIG · YAGMAIL

yagmail

communicationpythonv0.16.0

Install

4.6s avg

Import

441ms

Disk

60MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.16.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.461s · 60.4MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 4.6s · import 0.420s · 63MB

60MB installed

● package 60MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SMTP

✓ from yagmail import SMTP

This quickstart demonstrates sending a basic email using yagmail with an App Password (recommended over your main Gmail password). For enhanced security, especially in production, consider setting up OAuth2 authentication as detailed in yagmail's documentation. Ensure your sender email and password (or app password) are configured, ideally via environment variables.

import yagmail import os # It's recommended to use App Passwords for Gmail or OAuth2. # Store your email and app password in environment variables for security. # For OAuth2, configure it via yagmail.SMTP('your_email@gmail.com', oauth2_file='path/to/oauth2_creds.json') # See yagmail docs for detailed OAuth2 setup. SENDER_EMAIL = os.environ.get('YAGMAIL_SENDER_EMAIL', 'your_email@gmail.com') SENDER_APP_PASSWORD = os.environ.get('YAGMAIL_SENDER_APP_PASSWORD', 'your_app_password') RECIPIENT_EMAIL = os.environ.get('YAGMAIL_RECIPIENT_EMAIL', 'recipient@example.com') try: # Initialize yagmail with your Gmail account and app password yag = yagmail.SMTP(user=SENDER_EMAIL, password=SENDER_APP_PASSWORD) # Send an email subject = 'Hello from yagmail!' contents = [ 'This is the body of the email.', 'You can also send HTML content.', 'This is bold HTML content!' ] yag.send( to=RECIPIENT_EMAIL, subject=subject, contents=contents ) print(f'Email sent successfully from {SENDER_EMAIL} to {RECIPIENT_EMAIL}') except Exception as e: print(f'Failed to send email: {e}')

Debug

Known issues

breakingGoogle has deprecated 'Less secure app access'. Older tutorials suggesting this method will no longer work. Attempting to use your main Gmail password without 2FA and an App Password will result in an `SMTPAuthenticationError` or similar.

fix

Use Google App Passwords for programmatic access (if 2FA is enabled) or configure OAuth2 authentication. Refer to Google's and yagmail's official documentation for setup.

affects: All versions (due to Google's policy change)

gotchaProviding your main Gmail password directly in the script is a security risk and is discouraged. yagmail prefers using `keyring` for secure storage or OAuth2.

fix

Utilize `keyring` (installed with `yagmail[all]`) to securely store credentials (`yagmail.register('your_email@gmail.com', 'your_password')`) or implement OAuth2 as per yagmail's documentation. For basic use, consider environment variables for App Passwords.

affects: All versions

gotchaWhen sending HTML content, newline characters (\n) in plain strings might be automatically converted to ` ` tags. This behavior can be unexpected if you're mixing plain text and HTML.

fix

Ensure your HTML content is explicitly formatted as HTML. For pure plain text, use separate entries in the `contents` list. If experiencing issues, explicitly wrap HTML in `yagmail.inline()` or use HTML files as attachments.

affects: Potentially all versions (reported in older issues, behavior might persist for certain content types)

gotchaInstallation with `pip install yagmail[all]` can sometimes fail due to `keyring` or `dkimpy` dependencies, especially on certain operating systems or Python environments.

fix

If `pip install yagmail[all]` fails, try `pip install yagmail` first, then install `keyring` and `dkimpy` separately if needed and troubleshoot their individual installations.

affects: All versions

gotchaWhen using `yagmail.SMTP()`, if no explicit 'to' argument is provided in `send()`, the email defaults to being sent to the sender's own address.

fix

Always explicitly specify the 'to' recipient using `to='recipient@example.com'` or a list of recipients.

affects: All versions

Errors

Common errors & fixes

SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted. Learn more at https://support.google.com/mail/?p=BadCredentials')

Gmail typically requires an App Password when 2-Factor Authentication (2FA) is enabled for programmatic access, as regular passwords arehed.

fix

Generate and use an App Password from your Google Account security settings (myaccount.google.com/apppasswords) instead of your regular Gmail password.

ModuleNotFoundError: No module named 'yagmail'

The `yagmail` library has not been installed in the Python environment where your code is being executed.

fix

Install the library using pip: `pip install yagmail`

ValueError: Password is required, either specify it or use oauth2

The `yagmail.SMTP()` constructor requires a password or an OAuth2 configuration, neither of which was provided or properly configured.

fix

Provide your Gmail password (an App Password is recommended for 2FA accounts) as the second argument: `yag = yagmail.SMTP('your_email@gmail.com', 'your_app_password')`

ConnectionRefusedError: [Errno 111] Connection refused

Your system or network environment, such as a firewall or antivirus software, is actively blocking the outgoing connection attempt to Gmail's SMTP server.

fix

Ensure your firewall, antivirus, or network settings are not blocking outbound connections on SMTP ports (587 for TLS, 465 for SSL) and that you have a stable internet connection.

Upgrade

Version history

0.16.0latest on PyPI · released May 26, 2026

Audit

Dependencies

premailerrequiredUsed for inline CSS in HTML emails.

keyringoptionalRecommended for securely storing credentials, avoiding plain-text passwords in scripts.

dkimpyoptionalFor DomainKeys Identified Mail (DKIM) signing.

Agent activity

47 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kootenpv/yagmail ↗

packagehttps://pypi.org/project/yagmail/ ↗