API Reference

This page displays a full reference of yagmail's API.

Authentication

yagmail.register(username: str, password: str) → None

Use this to add a new gmail account to your OS’ keyring so it can be used in yagmail

Another way of authenticating is by passing an oauth2_file to yagmail.Client (or yagmail.AsyncClient), which is among the safest methods of authentication. Please see the OAuth2 section of the README for further details.

It is also possible to simply pass the password to yagmail.Client / yagmail.AsyncClient. If no password is given, yagmail will prompt the user for a password and then store the result in the keyring.

Mail Clients

class yagmail.Client(user: str | None = None, password: str | Dict[str, Any] | None = None, host: str = 'smtp.gmail.com', port: str | int | None = None, smtp_starttls: bool | dict | None = None, smtp_ssl: bool = True, smtp_set_debuglevel: int = 0, smtp_skip_login: bool = False, encoding: str = 'utf-8', oauth2_file: str | None = None, soft_email_validation: bool = True, dkim: DKIM | None = None, **kwargs: Any)

yagmail.Client is a magic wrapper around smtplib’s SMTP connection, and allows messages to be sent.

close() → None

Close the connection to the SMTP server

feedback(message: str = 'Awesome features! You made my day! How can I contribute?') → None

Most important function. Please send me feedback :-)

login() → None

Connect and login to the SMTP server.

send(to: str | List[str] | Tuple[str, ...] | Dict[str, str] | None = None, subject: str | List[str] | None = None, contents: Any | None = None, attachments: Any | None = None, cc: str | List[str] | Tuple[str, ...] | Dict[str, str] | None = None, bcc: str | List[str] | Tuple[str, ...] | Dict[str, str] | None = None, preview_only: bool = False, headers: Dict[str, str] | None = None, prettify_html: bool = True, message_id: str | None = None, group_messages: bool = True) → Tuple[List[str], str] | Dict[str, Any] | bool

Use this to send an email with gmail

send_unsent() → None

Emails that were not being able to send will be stored in self.unsent. Use this function to attempt to send these again

set_logging(log_level: int | None = 40, file_path_name: str | None = None) → None

This function allows to change the logging backend, either output or file as backend It also allows to set the logging level (whether to display only critical/error/info/debug. for example:

yag = yagmail.Client()
yag.set_logging(yagmail.logging.DEBUG)  # to see everything

and:

yagmail.set_logging(yagmail.logging.DEBUG, 'somelocalfile.log')

lastly, a log_level of None will make sure there is no I/O.

class yagmail.AsyncClient(user: str | None = None, password: str | Dict[str, Any] | None = None, host: str = 'smtp.gmail.com', port: str | int | None = None, smtp_starttls: bool | dict | None = None, smtp_ssl: bool = True, smtp_set_debuglevel: int = 0, smtp_skip_login: bool = False, encoding: str = 'utf-8', oauth2_file: str | None = None, soft_email_validation: bool = True, dkim: DKIM | None = None, **kwargs: Any)

Asynchronous version of yagmail.Client. Provides non-blocking versions of login, send, send_unsent, and close using Python’s built-in asyncio event loop and raw socket streams.

async aclose() → None

Close the SMTP connection asynchronously.

async close() → None

Synchronous-like close method that raises error to match aioyagmail API.

async login() → None

Connect and login to the SMTP server asynchronously.

async send(to: str | List[str] | Tuple[str, ...] | Dict[str, str] | None = None, subject: str | List[str] | None = None, contents: Any | None = None, attachments: Any | None = None, cc: str | List[str] | Tuple[str, ...] | Dict[str, str] | None = None, bcc: str | List[str] | Tuple[str, ...] | Dict[str, str] | None = None, preview_only: bool = False, headers: Dict[str, str] | None = None, prettify_html: bool = True, message_id: str | None = None, group_messages: bool = True) → Tuple[List[str], str] | Dict[str, Any] | bool

Send an email asynchronously.

async send_unsent() → None

Attempt to send unsent emails asynchronously.

DKIM

class yagmail.dkim.DKIM(domain, private_key, include_headers, selector)

domain: bytes

Alias for field number 0

include_headers: List[bytes] | None

Alias for field number 2

private_key: bytes

Alias for field number 1

selector: bytes

Alias for field number 3

E-Mail Contents

class yagmail.raw

Ensure that a string is treated as text and will not receive ‘magic’.

class yagmail.inline

Only needed when wanting to inline an image rather than attach it

Exceptions

Contains the exceptions

exception yagmail.error.YagAddressError

This means that the address was given in an invalid format. Note that From can either be a string, or a dictionary where the key is an email, and the value is an alias {‘sample@gmail.com’, ‘Sam’}. In the case of ‘to’, it can either be a string (email), a list of emails (email addresses without aliases) or a dictionary where keys are the email addresses and the values indicate the aliases. Furthermore, it does not do any validation of whether an email exists.

exception yagmail.error.YagConnectionClosed

The connection object has been closed by the user. This object can be used to send emails again after logging in, using self.login().

exception yagmail.error.YagInvalidEmailAddress

Note that this will only filter out syntax mistakes in emailaddresses. If a human would think it is probably a valid email, it will most likely pass. However, it could still very well be that the actual emailaddress has simply not be claimed by anyone (so then this function fails to devalidate).

Utilities

yagmail.validate.validate_email_with_regex(email_address: str) → None

Note that this will only filter out syntax mistakes in emailaddresses. If a human would think it is probably a valid email, it will most likely pass. However, it could still very well be that the actual emailaddress has simply not be claimed by anyone (so then this function fails to devalidate).