{"id":32176156,"url":"https://github.com/jeremyephron/simplegmail","last_synced_at":"2026-02-21T13:01:23.355Z","repository":{"id":38125860,"uuid":"173099184","full_name":"jeremyephron/simplegmail","owner":"jeremyephron","description":"A simple Gmail API client for applications in Python","archived":false,"fork":false,"pushed_at":"2025-02-07T02:23:37.000Z","size":85,"stargazers_count":398,"open_issues_count":37,"forks_count":84,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-10-24T07:45:26.489Z","etag":null,"topics":["api","email","gmail","gmail-api","pypi-package","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeremyephron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"jeremyephron"}},"created_at":"2019-02-28T11:23:03.000Z","updated_at":"2025-10-17T19:12:11.000Z","dependencies_parsed_at":"2024-06-18T22:54:19.596Z","dependency_job_id":null,"html_url":"https://github.com/jeremyephron/simplegmail","commit_stats":{"total_commits":97,"total_committers":11,"mean_commits":8.818181818181818,"dds":"0.41237113402061853","last_synced_commit":"7e1dcb9d0f6214581095b38965325c3ba08f3543"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/jeremyephron/simplegmail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyephron%2Fsimplegmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyephron%2Fsimplegmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyephron%2Fsimplegmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyephron%2Fsimplegmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeremyephron","download_url":"https://codeload.github.com/jeremyephron/simplegmail/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyephron%2Fsimplegmail/sbom","scorecard":{"id":515538,"data":{"date":"2025-08-11","repo":{"name":"github.com/jeremyephron/simplegmail","commit":"b48c8ecb573d3b82f34eeadd1e41729cd82fc51b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.1,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/python-publish.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Code-Review","score":0,"reason":"Found 1/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/jeremyephron/simplegmail/python-publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/jeremyephron/simplegmail/python-publish.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:23","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:24","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v4.1.1 not signed: https://api.github.com/repos/jeremyephron/simplegmail/releases/95373698","Warn: release artifact v4.1.0 not signed: https://api.github.com/repos/jeremyephron/simplegmail/releases/95331079","Warn: release artifact v4.0.4 not signed: https://api.github.com/repos/jeremyephron/simplegmail/releases/51924841","Warn: release artifact v4.1.1 does not have provenance: https://api.github.com/repos/jeremyephron/simplegmail/releases/95373698","Warn: release artifact v4.1.0 does not have provenance: https://api.github.com/repos/jeremyephron/simplegmail/releases/95331079","Warn: release artifact v4.0.4 does not have provenance: https://api.github.com/repos/jeremyephron/simplegmail/releases/51924841"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 2 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-20T01:43:50.649Z","repository_id":38125860,"created_at":"2025-08-20T01:43:50.650Z","updated_at":"2025-08-20T01:43:50.650Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29681468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T12:30:22.644Z","status":"ssl_error","status_checked_at":"2026-02-21T12:29:55.402Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","email","gmail","gmail-api","pypi-package","python","python3"],"created_at":"2025-10-21T19:55:05.824Z","updated_at":"2026-02-21T13:01:23.348Z","avatar_url":"https://github.com/jeremyephron.png","language":"Python","readme":"# simplegmail\n[![PyPI Downloads](https://img.shields.io/pypi/dm/simplegmail.svg?label=PyPI%20downloads)](\nhttps://pypi.org/project/simplegmail/)\n\nA simple Gmail API client in Python for applications.\n\n---\n\nCurrently Supported Behavior:\n- Sending html messages\n- Sending messages with attachments\n- Sending messages with your Gmail account signature\n- Retrieving messages with the full suite of Gmail's search capabilities\n- Retrieving messages with attachments, and downloading attachments\n- Modifying message labels (includes marking as read/unread, important/not \n  important, starred/unstarred, trash/untrash, inbox/archive)\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Send a simple message](#send-a-simple-message)\n    - [Send a message with attachments, cc, bcc fields](#send-a-message-with-attachments-cc-bcc-fields)\n    - [Retrieving messages](#retrieving-messages)\n    - [Marking messages](#marking-messages)\n    - [Changing message labels](#changing-message-labels)\n    - [Downloading attachments](#downloading-attachments)\n    - [Retrieving messages with queries](#retrieving-messages-advanced-with-queries)\n    - [Retrieving messages with more advanced queries](#retrieving-messages-more-advanced-with-more-queries)\n- [Feedback](#feedback)\n\n## Getting Started\n\nThe only setup required is to download an OAuth 2.0 Client ID file from Google\nthat will authorize your application.\n\nThis can be done at: https://console.developers.google.com/apis/credentials.\nFor those who haven't created a credential for Google's API, after clicking the \nlink above (and logging in to the appropriate account),\n\n1. Select/create the project that this authentication is for (if creating a new \nproject make sure to configure the OAuth consent screen; you only need to set \nan Application name)\n\n2. Click on the \"Dashboard\" tab, then \"Enable APIs and Services\". Search for \nGmail and enable.\n\n3. Click on the Credentials tab, then \"Create Credentials\" \u003e \"OAuth client ID\".\n\n4. Select what kind of application this is for, and give it a memorable name.\nFill out all necessary information for the credential (e.g., if choosing \n\"Web Application\" make sure to add an Authorized Redirect URI. See \nhttps://developers.google.com/identity/protocols/oauth2 for more infomation).\n\n5. Back on the credentials screen, click the download icon next to the \ncredential you just created to download it as a JSON object.\n\n6. Save this file as \"client_secret.json\" and place it in the root directory of \nyour application. (The `Gmail` class takes in an argument for the name of this \nfile if you choose to name it otherwise.)\n\nThe first time you create a new instance of the `Gmail` class, a browser window \nwill open, and you'll be asked to give permissions to the application. This \nwill save an access token in a file named \"gmail-token.json\", and only needs to \noccur once.\n\nAdditionally, you will need to ensure IMAP is enabled in your Gmail account\nsettings.\n\nYou are now good to go!\n\nNote about authentication method: I have opted not to use a username-password \nauthentication (through imap/smtp), since using Google's authorization is both \nsignificantly safer and avoids clashing with Google's many security measures.\n\n## Installation\n\nInstall using `pip` (Python3).\n\n```bash\npip3 install simplegmail\n```\n\n## Usage\n\n### Send a simple message:\n\n```python\nfrom simplegmail import Gmail\n\ngmail = Gmail() # will open a browser window to ask you to log in and authenticate\n\nparams = {\n  \"to\": \"you@youremail.com\",\n  \"sender\": \"me@myemail.com\",\n  \"subject\": \"My first email\",\n  \"msg_html\": \"\u003ch1\u003eWoah, my first email!\u003c/h1\u003e\u003cbr /\u003eThis is an HTML email.\",\n  \"msg_plain\": \"Hi\\nThis is a plain text email.\",\n  \"signature\": True  # use my account signature\n}\nmessage = gmail.send_message(**params)  # equivalent to send_message(to=\"you@youremail.com\", sender=...)\n```\n\n### Send a message with attachments, cc, bcc fields:\n\n```python\nfrom simplegmail import Gmail\n\ngmail = Gmail()\n\nparams = {\n  \"to\": \"you@youremail.com\",\n  \"sender\": \"me@myemail.com\",\n  \"cc\": [\"bob@bobsemail.com\"],\n  \"bcc\": [\"marie@gossip.com\", \"hidden@whereami.com\"],\n  \"subject\": \"My first email\",\n  \"msg_html\": \"\u003ch1\u003eWoah, my first email!\u003c/h1\u003e\u003cbr /\u003eThis is an HTML email.\",\n  \"msg_plain\": \"Hi\\nThis is a plain text email.\",\n  \"attachments\": [\"path/to/something/cool.pdf\", \"path/to/image.jpg\", \"path/to/script.py\"],\n  \"signature\": True  # use my account signature\n}\nmessage = gmail.send_message(**params)  # equivalent to send_message(to=\"you@youremail.com\", sender=...)\n```\n\nIt couldn't be easier!\n\n### Retrieving messages:\n\n```python\nfrom simplegmail import Gmail\n\ngmail = Gmail()\n\n# Unread messages in your inbox\nmessages = gmail.get_unread_inbox()\n\n# Starred messages\nmessages = gmail.get_starred_messages()\n\n# ...and many more easy to use functions can be found in gmail.py!\n\n# Print them out!\nfor message in messages:\n    print(\"To: \" + message.recipient)\n    print(\"From: \" + message.sender)\n    print(\"Subject: \" + message.subject)\n    print(\"Date: \" + message.date)\n    print(\"Preview: \" + message.snippet)\n    \n    print(\"Message Body: \" + message.plain)  # or message.html\n```\n\n### Marking messages:\n\n```python\nfrom simplegmail import Gmail\n\ngmail = Gmail()\n\nmessages = gmail.get_unread_inbox()\n\nmessage_to_read = messages[0]\nmessage_to_read.mark_as_read()\n\n# Oops, I want to mark as unread now\nmessage_to_read.mark_as_unread()\n\nmessage_to_star = messages[1]\nmessage_to_star.star()\n\nmessage_to_trash = messages[2]\nmessage_to_trash.trash()\n\n# ...and many more functions can be found in message.py!\n```\n\n### Changing message labels:\n\n```python\nfrom simplegmail import Gmail\n\ngmail = Gmail()\n\n# Get the label objects for your account. Each label has a specific ID that \n# you need, not just the name!\nlabels = gmail.list_labels()\n\n# To find a label by the name that you know (just an example):\nfinance_label = list(filter(lambda x: x.name == 'Finance', labels))[0]\n\nmessages = gmail.get_unread_inbox()\n\n# We can add/remove a label\nmessage = messages[0]\nmessage.add_label(finance_label) \n\n# We can \"move\" a message from one label to another\nmessage.modify_labels(to_add=labels[10], to_remove=finance_label)\n\n# ...check out the code in message.py for more!\n```\n\n### Downloading attachments:\n\n```python\nfrom simplegmail import Gmail\n\ngmail = Gmail()\n\nmessages = gmail.get_unread_inbox()\n\nmessage = messages[0]\nif message.attachments:\n    for attm in message.attachments:\n        print('File: ' + attm.filename)\n        attm.save()  # downloads and saves each attachment under it's stored\n                     # filename. You can download without saving with `attm.download()`\n\n```\n\n### Retrieving messages (advanced, with queries!):\n\n```python\nfrom simplegmail import Gmail\nfrom simplegmail.query import construct_query\n\ngmail = Gmail()\n\n# Unread messages in inbox with label \"Work\"\nlabels = gmail.list_labels()\nwork_label = list(filter(lambda x: x.name == 'Work', labels))[0]\n\nmessages = gmail.get_unread_inbox(labels=[work_label])\n\n# For even more control use queries:\n# Messages that are: newer than 2 days old, unread, labeled \"Finance\" or both \"Homework\" and \"CS\"\nquery_params = {\n    \"newer_than\": (2, \"day\"),\n    \"unread\": True,\n    \"labels\":[[\"Work\"], [\"Homework\", \"CS\"]]\n}\n\nmessages = gmail.get_messages(query=construct_query(query_params))\n\n# We could have also accomplished this with\n# messages = gmail.get_unread_messages(query=construct_query(newer_than=(2, \"day\"), labels=[[\"Work\"], [\"Homework\", \"CS\"]]))\n# There are many, many different ways of achieving the same result with search.\n```\n\n### Retrieving messages (more advanced, with more queries!):\n\n```python\nfrom simplegmail import Gmail\nfrom simplegmail.query import construct_query\n\ngmail = Gmail()\n\n# For even more control use queries:\n# Messages that are either:\n#   newer than 2 days old, unread, labeled \"Finance\" or both \"Homework\" and \"CS\"\n#     or\n#   newer than 1 month old, unread, labeled \"Top Secret\", but not starred.\n\nlabels = gmail.list_labels()\n\n# Construct our two queries separately\nquery_params_1 = {\n    \"newer_than\": (2, \"day\"),\n    \"unread\": True,\n    \"labels\":[[\"Finance\"], [\"Homework\", \"CS\"]]\n}\n\nquery_params_2 = {\n    \"newer_than\": (1, \"month\"),\n    \"unread\": True,\n    \"labels\": [\"Top Secret\"],\n    \"exclude_starred\": True\n}\n\n# construct_query() will create both query strings and \"or\" them together.\nmessages = gmail.get_messages(query=construct_query(query_params_1, query_params_2))\n```\n\nFor more on what you can do with queries, read the docstring for `construct_query()` in `query.py`.\n\n## Feedback\n\nIf there is functionality you'd like to see added, or any bugs in this project,\nplease let me know by posting an issue or submitting a pull request!\n","funding_links":["https://github.com/sponsors/jeremyephron"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyephron%2Fsimplegmail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremyephron%2Fsimplegmail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyephron%2Fsimplegmail/lists"}