simplegmail

library4.1.1pypypi✓ verified 83d ago

SimpleGmail is a Python library providing a simple API client for Gmail, allowing users to send, read, delete, and manage emails and labels via the Gmail API. The latest version is 4.1.1 (released 2025-11-07). The library follows an irregular release cadence.

communication http-networking crm-productivity

pip install simplegmail

github ↗package ↗

INSTALL

IMPORT

SIG · SIMPLEGMAIL

simplegmail

communicationpythonv4.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Gmail

✓ from simplegmail import Gmail

Always import base class

Message

✓ from simplegmail import Message

construct_query

✓ from simplegmail import construct_query

Quickstart: Initialize Gmail (triggers OAuth if needed) and list inbox messages.

from simplegmail import Gmail gmail = Gmail() # will prompt OAuth if no token # Get all inbox messages messages = gmail.get_inbox() for msg in messages: print(f"Subject: {msg.subject}") print(f"From: {msg.sender}") print(f"Snippet: {msg.snippet}\n")

Debug

Known issues

breakingIn v4.0.0, `exclude_labels` parameter behavior changed: previously it was a boolean to negate all labels, now it accepts a label string to exclude. Code using old pattern will break.

fix

Change `construct_query(labels='finance', exclude_labels=True)` to `construct_query(exclude_labels='finance')`

affects: <4.0.0

deprecatedThe `creds_file` parameter was removed in v3.1.5 and replaced with 'creds' and 'token' parameters. The quickstart no longer supports old credential file specification.

fix

Use 'creds' (credentials.json path) and 'token' (pickle file path) arguments when constructing Gmail.

affects: <3.1.5

gotchaWhen using `sender` with both name and email (e.g., 'John Doe <john@email.com>') and `signature=True`, the library may parse incorrectly. Fixed in v4.0.2.

fix

Upgrade to >=4.0.2 or avoid signature when using formatted sender string.

affects: 4.0.0 - 4.0.1

gotchaOAuth token expires hourly. In v4.0.4 and later, automatic refresh is implemented. In older versions, the token may expire mid-session causing `google.auth.exceptions.RefreshError`.

fix

Upgrade to >=4.0.4 or manually refresh token using `gmail.service.users().messages().list(...)` call after re-authentication.

affects: <=4.0.3

gotchaWhen using multithreaded downloads, many open sockets may accumulate if garbage collection is not triggered. Fixed in v4.1.1.

fix

Upgrade to v4.1.1 or call `gc.collect()` after large batch operations.

affects: <4.1.1

Errors

Common errors & fixes

google.auth.exceptions.RefreshError: ('invalid_grant: Bad Request', {'error': 'invalid_grant', 'error_description': 'Bad Request'})

OAuth token has expired and the library is older than v4.0.4, which cannot refresh automatically.

fix

Upgrade to >=4.0.4 or delete token.pickle and re-authenticate via Gmail() constructor.

TypeError: __init__() got an unexpected keyword argument 'creds_file'

Passing deprecated `creds_file` parameter to Gmail constructor in version >=3.1.5.

fix

Use `creds='path/to/credentials.json'` instead of `creds_file='path'`.

ValueError: The 'exclude_labels' parameter now takes a string label to exclude, not a boolean.

Using old v3.x pattern `construct_query(labels='finance', exclude_labels=True)` in v4.0.0+.

fix

Change to `construct_query(exclude_labels='finance')`.

AttributeError: 'Message' object has no attribute 'headers'

Accessing `headers` attribute on Message objects before v4.0.1, where it didn't exist.

fix

Upgrade to >=4.0.1 or access individual headers via `msg.sender`, `msg.subject` etc.

Upgrade

Version history

4.1.1latest on PyPI · released Mar 13, 2023

Audit

Dependencies

google-api-python-clientrequiredCore dependency for Gmail API interaction

google-auth-httplib2requiredUsed for authentication transport

google-auth-oauthlibrequiredHandles OAuth2 flow for token generation

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jeremyephron/simplegmail ↗

packagehttps://pypi.org/project/simplegmail/ ↗