SimpleGmail

4.1.1 verified Sat May 09 auth: no python

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.

pip install simplegmail

Common errors

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

cause 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.

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

cause 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'.

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

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

fix

Change to construct_query(exclude_labels='finance').

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

cause 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.

Warnings

breaking In 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')`

deprecated The `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.

gotcha When 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.

gotcha OAuth 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.

gotcha When 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.

Imports

Gmail
```
from simplegmail import Gmail
```
Always import base class
Message
```
from simplegmail import Message
```
construct_query
```
from simplegmail import construct_query
```

Quickstart

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