Gmail Connector

Python module to send SMS, emails and read emails in any folder.

As of May 30, 2022, Google no longer supports third party applications accessing Google accounts only using username and password (which was originally available through lesssecureapps)
An alternate approach is to generate apppasswords instead.
Reference: https://support.google.com/accounts/answer/6010255

Installation

pip install gmail-connector

Env Vars

Environment variables can be loaded from a .env file.

# For authentication
GMAIL_USER='[email protected]',
GMAIL_PASS='<ACCOUNT_PASSWORD>'

# For outbound emails
RECIPIENT='[email protected]'

# For outbound SMS
PHONE='1234567890'

Send SMS

import gmailconnector as gc

sms_object = gc.SendSMS()
auth = sms_object.authenticate  # Authentication happens before sending SMS if not instantiated separately
assert auth.ok, auth.body
response = sms_object.send_sms(phone='+11234567890', message='Test SMS using gmail-connector',
                               carrier='verizon', delete_sent=False)  # Stores the SMS in email's sent items
assert response.ok, response.json()
print(response.body)

Send Email

import gmailconnector as gc

mail_object = gc.SendEmail()
auth = mail_object.authenticate  # Authentication happens in send_email if not instantiated beforehand
assert auth.ok, auth.body

# Send a basic email
response = mail_object.send_email(recipient='[email protected]', subject='Howdy!')
assert response.ok, response.json()
print(response.body)

To verify recipient email before sending. Authentication not required, uses SMTP port 25

from gmailconnector import validator

email_addr = '[email protected]'
validation_result = validator.validate_email(email_address=email_addr)
if validation_result.ok is True:
    print('valid')  # Validated and found the recipient address to be valid
elif validation_result.ok is False:
    print('invalid')  # Validated and found the recipient address to be invalid
else:
    print('validation incomplete')  # Couldn't validate (mostly because port 25 is blocked by ISP)

import os
import gmailconnector as gc

mail_object = gc.SendEmail()
auth = mail_object.authenticate  # Authentication happens in send_email if not instantiated beforehand
assert auth.ok, auth.body

# Different use cases to add attachments with/without custom filenames to an email
images = [os.path.join(os.getcwd(), 'images', image) for image in os.listdir('images')]
names = ['Apple', 'Flower', 'Balloon']

# Use case 1 - Send an email with attachments but no custom attachment name
response = mail_object.send_email(recipient='[email protected]', subject='Howdy!',
                                  attachment=images)
assert response.ok, response.body
print(response.json())

# Use case 2 - Use a dictionary of attachments and custom attachment names
response = mail_object.send_email(recipient='[email protected]', subject='Howdy!',
                                  custom_attachment=dict(zip(images, names)))
assert response.ok, response.body
print(response.json())

# Use case 3 - Use list of attachments and list of custom attachment names
response = mail_object.send_email(recipient='[email protected]', subject='Howdy!',
                                  attachment=[images], filename=[names])
assert response.ok, response.body
print(response.json())

# Use case 4 - Use a single attachment and a custom attachment name for it
response = mail_object.send_email(recipient='[email protected]', subject='Howdy!',
                                  attachment=os.path.join('images', 'random_apple_xroamutiypa.jpeg'), filename='Apple')
assert response.ok, response.body
print(response.json())

Read Email

import datetime

import gmailconnector as gc

reader = gc.ReadEmail(folder=gc.Folder.all)
filter1 = gc.Condition.since(since=datetime.date(year=2010, month=5, day=1))
filter2 = gc.Condition.subject(subject="Security Alert")
filter3 = gc.Category.not_deleted
response = reader.instantiate(filters=(filter1, filter2, filter3))  # Apply multiple filters at the same time
assert response.ok, response.body
for each_mail in reader.read_mail(messages=response.body, humanize_datetime=False):  # False to get datetime object
    print(each_mail.date_time.date())
    print("[%s] %s" % (each_mail.sender_email, each_mail.sender))
    print("[%s] - %s" % (each_mail.subject, each_mail.body))

Linting

PreCommit will ensure linting, and the doc creation are run on every commit.

Requirement

pip install sphinx==5.1.1 pre-commit==2.20.0 recommonmark==0.7.1

Usage

pre-commit run --all-files

Change Log

Requirement

pip install changelog-generator

Usage

changelog reverse -f release_notes.rst -t 'Release Notes'

Pypi Module

https://pypi.org/project/gmail-connector/

Runbook

https://thevickypedia.github.io/gmail-connector/

Repository

thevickypedia/gmail-connector

License & copyright

© Vignesh Sivanandha Rao

Licensed under the MIT License