---
id: simplegmail
version: "4.1.1"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# simplegmail — A simple Python API client for Gmail.

License: permissive · Maintenance: dormant · Downloads: 110.1K/mo

## What it is and what it does

simplegmail is a thin Python wrapper around the Gmail API that abstracts away OAuth setup and raw API calls. It lets you send HTML or plain-text emails with attachments and signatures, retrieve messages using Gmail's search syntax, download attachments, and modify message labels (read/unread, starred, archived, etc.) from Python code.

The package handles the OAuth 2.0 flow automatically—on first use, it opens a browser window for you to grant permissions, then caches the token locally. It depends on google-api-python-client for API calls, beautifulsoup4 and lxml for HTML parsing, python-dateutil for date handling, and oauth2client for authentication. The library is stable and production-ready but dormant; the last release was in March 2023.

Use it for:

- Automate sending transactional or notification emails from a Python application without managing SMTP credentials.
- Build a script to bulk-download attachments from emails matching specific search criteria (e.g., invoices from a date range).
- Archive or label incoming emails programmatically based on sender, subject, or content rules.
- Retrieve and parse unread messages to feed into a data pipeline or chatbot.
- Sync Gmail labels and message metadata to an external database or dashboard.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python wrapper around the Gmail API that handles authentication, sending messages with attachments, retrieving and searching emails, and managing labels and message state.

Yes, if you need a straightforward Gmail API wrapper and are comfortable with dormant maintenance. The package is stable, has no known vulnerabilities, and low install friction. However, be aware that oauth2client is deprecated by Google; if you need active development or modern auth practices, consider evaluating google-auth-based alternatives or contributing to this project.

## Install

pip install simplegmail
uv add simplegmail
poetry add simplegmail

## Installing simplegmail

Before you install: Low install friction with a pure-Python wheel. Maintenance is dormant—last release was 2023-03-13 and last commit 2025-02-07, so the package is stable but not actively developed. No known vulnerabilities.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install simplegmail

from simplegmail import Gmail

gmail = Gmail()  # Opens browser for OAuth consent on first run
messages = gmail.get_unread_inbox()
for msg in messages:
    print(msg.subject, msg.sender)

Requires a Google OAuth 2.0 Client ID JSON file (client_secret.json) downloaded from Google Cloud Console; first instantiation opens a browser for authentication.

Verify before relying:

- Whether oauth2client (a deprecated Google auth library) is still functional with current Google API versions or if migration to google-auth is planned.
- Current state of beautifulsoup4 and lxml usage for HTML parsing—whether they handle modern email HTML robustly.

## Package facts

- License: not declared (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 110.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gmail api python client, send email via gmail api, retrieve gmail messages python, gmail label management, gmail attachment download, gmail search query python, oauth gmail automation, email-automation, oauth2, gmail-api

[View on SkillFed](https://skillfed.io/packages/simplegmail) · [View on PyPI](https://pypi.org/project/simplegmail/)