gmail-connector 0.6.3

Python module to, send SMS, emails and read unread emails.

Gmail Connector

Python module to, send SMS, emails and read unread 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 passwords instead.
Reference: https://support.google.com/accounts/answer/6010255

Installation

pip install gmail-connector

Env Vars

Store a .env file with the args:

gmail_user = '[e-mail]',
gmail_pass = '<ACCOUNT_PASSWORD>'

Optionally include,

recipient='[e-mail]'
phone='1234567890'

Send SMS

from gmailconnector.send_sms import Messenger

sms_object = Messenger()
auth = sms_object.authenticate  # Authentication happens in send_sms if not instantiated beforehand
if not auth.ok:
    exit(auth.body)
response = sms_object.send_sms(phone='[phone]', message='Test SMS using gmail-connector')
if response.ok:
    print(response.json())

More on Send SMS

:warning: Gmail's SMS Gateway has a payload limit. So, it is recommended to break larger messages into multiple SMS.

Additional args:

• subject: Subject of the message. Defaults to Message from GmailConnector
• carrier: Use any of at&t, t-mobile, verizon, boost, cricket, us-cellular. Defaults to t-mobile.
• sms_gateway: SMS gateway of the carrier. Defaults to tmomail.net since the default carrier is t-mobile.
• delete_sent: Boolean flag to delete the outbound email from SentItems. Defaults to True

Note: If known, using the sms_gateway will ensure proper delivery of the SMS.

Send Email

import os

from gmailconnector.send_email import SendEmail

mail_object = SendEmail()
auth = mail_object.authenticate  # Authentication happens in send_email if not instantiated beforehand
if not auth.ok:
    exit(auth.body)

# Send an email without any attachments
response = mail_object.send_email(recipient='[e-mail]', subject='Howdy!')
print(response.json())

# 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='[e-mail]', subject='Howdy!',
                                  attachment=images)
print(response.json())

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

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

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

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

from gmailconnector.validator import validate_email

email_addr = '[e-mail]'
validation_result = 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)

More on Send Email

Additional args:

• body: Body of the email. Defaults to blank.
• html_body: Body of the email formatted as HTML. Supports inline images with a public src.
• attachment: Filename(s) that has to be attached.
• filename: Custom name(s) for the attachment(s). Defaults to the attachment name itself.
• sender: Name that has to be used in the email.
• cc: Email address of the recipient to whom the email has to be CC'd.
• bcc: Email address of the recipient to whom the email has to be BCC'd.

Note: To send email to more than one recipient, wrap recipient/cc/bcc in a list.

recipient=['[e-mail]', '[e-mail]']

Read Email

from gmailconnector.read_email import ReadEmail

reader = ReadEmail(folder='"[Gmail]/All Mail"')  # Folder defaults to inbox
response = reader.instantiate(category='SMALLER 500')  # Search criteria defaults to UNSEEN
if response.ok:
    unread_emails = reader.read_email(response.body)
    for each_mail in list(unread_emails):
        print(each_mail)
else:
    print(response.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 --no-cache --upgrade 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

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

License & copyright

© Vignesh Sivanandha Rao, Gmail Connector

Licensed under the MIT License