{"id":28182,"library":"simplegmail","title":"SimpleGmail","description":"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.","status":"active","version":"4.1.1","language":"python","source_language":"en","source_url":"https://github.com/jeremyephron/simplegmail","tags":["gmail","email","api-client","google-api","oauth"],"install":[{"cmd":"pip install simplegmail","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for Gmail API interaction","package":"google-api-python-client","optional":false},{"reason":"Used for authentication transport","package":"google-auth-httplib2","optional":false},{"reason":"Handles OAuth2 flow for token generation","package":"google-auth-oauthlib","optional":false}],"imports":[{"note":"Always import base class","symbol":"Gmail","correct":"from simplegmail import Gmail"},{"note":"","symbol":"Message","correct":"from simplegmail import Message"},{"note":"","symbol":"construct_query","correct":"from simplegmail import construct_query"}],"quickstart":{"code":"from simplegmail import Gmail\n\ngmail = Gmail()  # will prompt OAuth if no token\n\n# Get all inbox messages\nmessages = gmail.get_inbox()\nfor msg in messages:\n    print(f\"Subject: {msg.subject}\")\n    print(f\"From: {msg.sender}\")\n    print(f\"Snippet: {msg.snippet}\\n\")","lang":"python","description":"Quickstart: Initialize Gmail (triggers OAuth if needed) and list inbox messages."},"warnings":[{"fix":"Change `construct_query(labels='finance', exclude_labels=True)` to `construct_query(exclude_labels='finance')`","message":"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.","severity":"breaking","affected_versions":"<4.0.0"},{"fix":"Use 'creds' (credentials.json path) and 'token' (pickle file path) arguments when constructing Gmail.","message":"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.","severity":"deprecated","affected_versions":"<3.1.5"},{"fix":"Upgrade to >=4.0.2 or avoid signature when using formatted sender string.","message":"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.","severity":"gotcha","affected_versions":"4.0.0 - 4.0.1"},{"fix":"Upgrade to >=4.0.4 or manually refresh token using `gmail.service.users().messages().list(...)` call after re-authentication.","message":"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`.","severity":"gotcha","affected_versions":"<=4.0.3"},{"fix":"Upgrade to v4.1.1 or call `gc.collect()` after large batch operations.","message":"When using multithreaded downloads, many open sockets may accumulate if garbage collection is not triggered. Fixed in v4.1.1.","severity":"gotcha","affected_versions":"<4.1.1"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Upgrade to >=4.0.4 or delete token.pickle and re-authenticate via Gmail() constructor.","cause":"OAuth token has expired and the library is older than v4.0.4, which cannot refresh automatically.","error":"google.auth.exceptions.RefreshError: ('invalid_grant: Bad Request', {'error': 'invalid_grant', 'error_description': 'Bad Request'})"},{"fix":"Use `creds='path/to/credentials.json'` instead of `creds_file='path'`.","cause":"Passing deprecated `creds_file` parameter to Gmail constructor in version >=3.1.5.","error":"TypeError: __init__() got an unexpected keyword argument 'creds_file'"},{"fix":"Change to `construct_query(exclude_labels='finance')`.","cause":"Using old v3.x pattern `construct_query(labels='finance', exclude_labels=True)` in v4.0.0+.","error":"ValueError: The 'exclude_labels' parameter now takes a string label to exclude, not a boolean."},{"fix":"Upgrade to >=4.0.1 or access individual headers via `msg.sender`, `msg.subject` etc.","cause":"Accessing `headers` attribute on Message objects before v4.0.1, where it didn't exist.","error":"AttributeError: 'Message' object has no attribute 'headers'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}