Gmail

Overview

The Gmail module leverages the Gmail API and provides an way to easily send notifications through email. It is recommended that you reference the Gmail API documentation for additional details and information.

Credentials and token

  • Credentials are required to use the class

  • You will need to pass in the path to the credentials and to where a generated token will be saved. Typically you’ll get the credentials from the Google Developer Console (look for the “Gmail API”).

6MB Attachment Size Limit

  • Currently there is a limit of 6MB when sending attachments.

Quickstart

Configure credentials
from parsons import Gmail
gmail = Gmail(
   creds_path="~/secret_location/credentials.json",
   token_path="~/secret_location/token.json",
)
Send an email
gmail.send_email(
   "sender@email.com",
   "recipient@email.com",
   "The Subject",
   "This is the text body of the email",
)
Send an email with HTML and/or attachments(s).
gmail.send_email(
   "sender@email.com",
   "recipient@email.com",
   "An html email with attachments",
   "This is the text body of the email",
   html="<p>This is the html part of the email</p>",
   files=['file1.txt', 'file2.txt'],
)

Additionally, you can create a raw email messages and send it. See below for more details.

API

class parsons.notifications.gmail.Gmail(creds_path=None, token_path=None, user_id='me')[source]

Create a Gmail object, for sending emails.

Parameters:

  • creds_path – str The path to the credentials.json file.

  • token_path – str The path to the token.json file.

  • user_id – str Optional; Sender email address. Defaults to the special value “me” which is used to indicate the authenticated user.

send_email(sender: str, to: str | list[str], subject: str, message_text: str, message_html: str | None = None, files: str | list[str] | None = None, *, check_deliverability: bool = False, dns_resolver: Resolver | None = None)

Send an email message.

Parameters:

  • sender (str) – Email address of the sender.

  • to (str | list[str]) – Email address(es) of the receiver(s). Must be in correct email string syntax. For example, name@email.com or "Name" <email@email.com>.

  • subject (str) – The subject of the email message.

  • message_text (str) – The text of the email message.

  • message_html (str | None) – The html formatted text of the email message. If ommitted, the email is sent a text-only body.

  • files (str | list[str] | None) – The path to the file(s) to be attached.

  • check_deliverability (bool)

  • dns_resolver (Resolver | None)

Keyword Arguments:

  • check_deliverability – Query DNS to ensure that the domain name(s) can receive mail.

  • dns_resolver – Caching dns resolver to reuse in each call. You can create one with email_validator.caching_resolver(timeout=10) If check_deliverability is not True, this has no effect. If resolver is not provided, but check_deliverability is True, one will be created with a 10 second timeout.

Raises:

EmptyListError – If to parameter is an empty list.

class parsons.notifications.sendmail.EmptyListError[source]

Throw when a list is empty that should contain at least 1 element.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.