Skip to main content

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

Project description

Pypi-version Python

pages-build-deployment pypi-publish

Pypi-format Pypi-status

GitHub Repo created GitHub commit activity GitHub last commit

Gmail Connector

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

Modules and Protocols
  • email - Format emails as MIMEMultipart object, read emails from bytes and str and decode headers.
  • smtplib - SMTP Simple Mail Transfer Protocol to connect to gmail server, do auth and perform outgoing tasks.
  • imaplib - IMAP Internet Message Access Protocol to access messages in an email mailbox.


pip install gmail-connector

Env Vars

Store a .env file with the args:

gmail_user = '',
gmail_pass = '<ACCOUNT_PASSWORD>'

Send SMS

from gmailconnector.send_sms import Messenger

response = Messenger(
    message='Test SMS using gmail-connector'
if response.ok:
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 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

from gmailconnector.send_email import SendEmail

response = SendEmail(
if response.ok:
More on Send Email
Additional args:
  • body: Body of the email. Defaults to blank.
  • attachment: Filename that has to be attached.
  • filename: Custom name for the attachment. 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=['', '']

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):


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

pip install --no-cache --upgrade sphinx pre-commit recommonmark

pre-commit run --all-files

Change Log

Requirement pip install --no-cache --upgrade changelog-generator

Usage changelog

Pypi Module



License & copyright

© Vignesh Sivanandha Rao, Gmail Connector

Licensed under the MIT License

Change Log

0.5.2 (06/08/2022)

  • Remove verbose and override flags when loading .env

0.5.1 (02/21/2022)

  • Update version compatibility in
  • Import local modules from init
  • Add a script to build locally
  • Remove docs from actions

0.5.0 (02/19/2022)

  • Add a warning if count is called outside ReadEmail
  • Strip string converted email info in the yielded dict

0.4.9 (02/19/2022)

  • Read mails in all folders with different status
  • Convert email receive time into local timezone
  • Remove print statements and use yield instead
  • Yield email information as a dictionary
  • Upload to pypi when committed to master
  • Update docs, and CHANGELOG

0.4.8 (01/12/2022)

  • Take a custom filename for the attachment
  • Default to attachment name without the path
  • Remove unnecessary variables

0.4.7 (01/09/2022)

  • Check for phone and recipient in env var
  • Take gmail username instead of email address

0.4.6 (01/08/2022)

  • Load env vars from a .env file
  • Reformat docstrings
  • Fix sent item after sending an SMS

0.4.5 (01/01/2022)

  • Add SMTP port number to send email

0.4.4 (12/30/2021)

  • Add more information to payload restriction

0.4.3 (12/30/2021)

  • Add payload limit for SMS

0.4.2 (12/22/2021)

  • Remove endpoint validator due to high inaccuracies

0.4.1 (12/22/2021)

  • Mark internal methods as private
  • Include private methods in sphinx docs

0.4.0 (12/22/2021)

  • Fix phone number digit validation

0.3.9 (12/20/2021)

  • Create a separate method to validate input arguments
  • Change arg phone_number to phone

0.3.8 (12/20/2021)

  • Fix import issues with module vs sphinx

0.3.7 (12/20/2021)

  • Specify carrier based sms-gateway to increase success rate
  • Introduce carrier, sms_gateway and delete_sent as optional arguments
  • Use a third-party email-validator to check endpoint before sending the email
  • Remove redundant variables
  • Add requirements.txt, update and .gitignore

0.3.6 (11/10/2021)

  • Return responses as a class object instead of a dictionary
  • Delete messages after sending an SMS
  • Do not remove docs directory if version is not bumped
  • Generate CHANGELOG in reverse

0.3.5 (10/16/2021)

  • Add project URLs and package requirements to pypi
  • Add markdown support to sphinx autodocs
  • Add a condition check for version upgrade
  • Update docs and changelog

0.3.4 (08/11/2021)

  • Add new lines to the message start to separate subject and body of the SMS
  • Update sphinx documentation to 4.1.2

0.3.3 (08/04/2021)

  • Fix incorrect HTTP return codes

0.3.2 (07/24/2021)

  • Remove logger module.
  • Add exception handlers for Messenger class.
  • Update docs and CHANGELOG
  • Bump version.

0.3.1 (07/22/2021)

  • Return a dictionary element after sending an email/SMS.
  • Add status code and description to return dict.
  • Update docs and CHANGELOG
  • Bump version.

0.3.0 (07/19/2021)

  • Allow users to add multiple recipients while sending email.
  • Add CC and BCC options.
  • Check if attachment file is available before trying to attach.
  • Wrap recipient, cc and bcc items in a single list before email kick off.
  • Remove sender arg and default to the user login email address.
  • Fix version number format.

0.2.9 (07/19/2021)

  • Add logging
  • Remove print statements
  • Bump version

0.2.8 (07/19/2021)

  • Bump version to support github action
  • Auto upload to pypi

0.2.7 (07/19/2021)

  • auto upload to pypi when tagged a release version

0.2.6 (07/19/2021)

  • onboard docs.yml but only prints a statement

0.2.5 (07/19/2021)

  • Add badges
  • Update and CHANGELOG
  • Bump version

0.2.4 (07/18/2021)

  • Onboard pypi module
  • Add, setup.cfg,, CHANGELOG
  • Update and docs
  • Move files to gmailconnector support package

0.2.3 (07/18/2021)

  • Increase page width and update

0.2.2 (07/18/2021)

  • Onboard and update docs

0.2.1 (07/17/2021)

  • Onboard sphinx auto generated documentation

0.2.0 (07/17/2021)

  • Refactor and add
  • Add pre-commit for linting
  • Update

0.1.9 (06/28/2020)

  • update

0.1.8 (06/28/2020)

  • add LICENSE

0.1.7 (06/28/2020)

  • look for env variables before failing

0.1.6 (06/27/2020)

  • included exception handler

0.1.5 (06/27/2020)

  • modify date time type standards instead of using index values

0.1.4 (06/11/2020)

  • fix typo

0.1.3 (06/09/2020)

  • improve coding standards

0.1.2 (06/08/2020)

  • improve coding standards

0.1.1 (06/08/2020)

  • added comments

0.1.0 (06/08/2020)

  • get user input before reading multiple emails

0.0.9 (06/08/2020)

  • get user input before showing any content

0.0.8 (06/08/2020)

  • include number of unread emails on top

0.0.7 (06/08/2020)

  • user input condition to read email

0.0.6 (06/08/2020)

  • pdt to cdt

0.0.5 (06/08/2020)

  • added time when the email was received

0.0.4 (06/08/2020)

  • decode body of the email and display only text part

0.0.3 (06/08/2020)

  • decode raw email using email library

0.0.2 (06/08/2020)

  • read raw email

0.0.1 (06/07/2020)

  • Initial commit

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gmail-connector-0.5.2.tar.gz (13.4 kB view hashes)

Uploaded source

Built Distribution

gmail_connector-0.5.2-py2.py3-none-any.whl (15.4 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page