{"id":27991648,"url":"https://github.com/adityagarg8/git-credential-email","last_synced_at":"2026-01-26T14:02:29.881Z","repository":{"id":290082850,"uuid":"973320386","full_name":"AdityaGarg8/git-credential-email","owner":"AdityaGarg8","description":"Git credential helpers for Microsoft Outlook, Gmail, Yahoo, AOL and Proton Mail accounts","archived":false,"fork":false,"pushed_at":"2026-01-21T08:08:29.000Z","size":333,"stargazers_count":24,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-21T19:25:05.690Z","etag":null,"topics":["aol","aolmail","git","git-credential-helper","git-email","gmail","oauth2","outlook","proton","protonmail","yahoo","yahoo-email"],"latest_commit_sha":null,"homepage":"https://gce.adityagarg.is-a.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdityaGarg8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","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,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["AdityaGarg8"],"custom":["https://www.buymeacoffee.com/gargadityav"]}},"created_at":"2025-04-26T18:26:14.000Z","updated_at":"2026-01-21T08:08:33.000Z","dependencies_parsed_at":"2025-04-26T19:30:59.275Z","dependency_job_id":"66dd9095-e4e8-4b66-af53-4a478cf5ecc3","html_url":"https://github.com/AdityaGarg8/git-credential-email","commit_stats":null,"previous_names":["adityagarg8/git-credential-outlook","adityagarg8/git-credential-outlook-and-gmail","adityagarg8/git-credential-email"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/AdityaGarg8/git-credential-email","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaGarg8%2Fgit-credential-email","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaGarg8%2Fgit-credential-email/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaGarg8%2Fgit-credential-email/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaGarg8%2Fgit-credential-email/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdityaGarg8","download_url":"https://codeload.github.com/AdityaGarg8/git-credential-email/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaGarg8%2Fgit-credential-email/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28780032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"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":["aol","aolmail","git","git-credential-helper","git-email","gmail","oauth2","outlook","proton","protonmail","yahoo","yahoo-email"],"created_at":"2025-05-08T17:37:39.297Z","updated_at":"2026-01-26T14:02:29.860Z","avatar_url":"https://github.com/AdityaGarg8.png","language":"Python","funding_links":["https://github.com/sponsors/AdityaGarg8","https://www.buymeacoffee.com/gargadityav"],"categories":[],"sub_categories":[],"readme":"# git-credential-email\n\nThis repo contains the following helpers:\n\n- `git-credential-gmail`: For Gmail accounts.\n- `git-credential-outlook`: For Microsoft Outlook accounts.\n- `git-credential-yahoo`: For Yahoo accounts.\n- `git-credential-aol`: For AOL accounts.\n- `git-msgraph`: Helper to use Microsoft Graph API instead of SMTP to send emails.\n- `git-protonmail`: Helper to use Proton Mail API to send emails.\n\nThey can be used with `git send-email`, especially when Outlook no longer supports app passwords.\n\n*`git-credential-fastmail` is planned but due to paid nature of the service, a paid account/sponsorship for such an account is needed for testing and maintainance. Anyone interested in helping may [raise an issue](https://github.com/AdityaGarg8/git-credential-email/issues).*\n\n## How does this work?\n\nIt is a simple python script, based on \u003chttps://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py\u003e and \u003chttps://github.com/opulentfox-29/protonmail-api-client\u003e. It does the following:\n\n- Uses an OAuth2.0 `client_id` and `client_secret` to authenticate with Microsoft/Google/Yahoo/AOL and retrieve a refresh token.\n- As per demand, it uses the refresh token to generate OAuth2.0 access tokens as and when required.\n- The refresh token and access token is stored securely using the `keyring` module of pip. More information about this can be read from \u003chttps://pypi.org/project/keyring/\u003e.\n- Everytime the helper is called, it passes the stored access token to git. If the access token has expired, the helper first refreshes it automatically and passes the new access token.\n- For APIs like Microsoft Graph and Proton Mail, it exploits the sendmail-like command ability of `git send-email`\n- For Proton Mail, the authentication flow is different. The helper uses the web API of Proton Mail to get the required keys for end to end encryption, store cookies in form of session file etc.\n\n## Installation\n\n### All platforms\n\n- Download the python script of the helper you want from [here](https://github.com/AdityaGarg8/git-credential-email/releases/latest).\n\n- Make sure that the script is [located in the path](https://superuser.com/a/284351/62691) and [is executable](https://askubuntu.com/a/229592/18504).\n\n- Install the `keyring` and `requests` pip module:\n\n  ```bash\n  pip install keyring requests\n  ```\n\n- For **Proton Mail**, you also need to install some more modules by running:\n\n  ```bash\n  pip install bcrypt cryptography keyring PGPy13 requests requests-toolbelt typing-extensions\n  ```\n\n### Linux\n\n#### Ubuntu/Debian\n\nRun the following to add the apt repo and install the helpers:\n\n```bash\ncurl -L \"https://github.com/AdityaGarg8/git-credential-email/releases/download/debian/KEY.gpg\" \\\n\t| gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/git-credential-email.gpg \u003e/dev/null \\\n\t\u0026\u0026 echo \"deb [signed-by=/etc/apt/trusted.gpg.d/git-credential-email.gpg] \\\n\thttps://github.com/AdityaGarg8/git-credential-email/releases/download/debian ./\" \\\n\t| sudo tee -a /etc/apt/sources.list.d/git-credential-email.list \\\n\t\u0026\u0026 sudo apt-get update \\\n\t\u0026\u0026 sudo apt-get install -y git-credential-gmail git-credential-outlook git-credential-yahoo git-credential-aol git-msgraph git-protonmail\n```\n\n#### Fedora\n\nRun the following to add the copr repo and install the helpers:\n\n```bash\nsudo dnf copr enable -y adityagarg8/git-credential-email\nsudo dnf install -y git-credential-gmail git-credential-outlook git-credential-yahoo git-credential-aol git-msgraph git-protonmail\n```\n\n#### Arch Linux\n\nEdit `/etc/pacman.conf` and add the following at its end:\n\n```bash\n[git-credential-email]\nServer = https://github.com/AdityaGarg8/git-credential-email/releases/download/archlinux\n```\n\nNow import the GPG Key used to sign the packages by running:\n\n```bash\nsudo pacman-key --recv-keys 48DC9F9CC66D3FAF --keyserver keyserver.ubuntu.com\nsudo pacman-key --lsign-key 48DC9F9CC66D3FAF\n```\n\nFinally install the helpers by running:\n\n```bash\nsudo pacman -Sy git-credential-gmail git-credential-outlook git-credential-yahoo git-credential-aol git-msgraph git-protonmail\n```\n\n**Note:** You may also have to install a supported keyring backend as described in \u003chttps://pypi.org/project/keyring/\u003e.\n\n#### OpenSUSE Tumbleweed\n\nRun the following to add the copr repo and install the helpers:\n\n```bash\nsudo zypper addrepo https://copr.fedorainfracloud.org/coprs/adityagarg8/git-credential-email/repo/opensuse-tumbleweed/adityagarg8-git-credential-email-opensuse-tumbleweed.repo\nsudo zypper install git-credential-gmail git-credential-outlook git-credential-yahoo git-credential-aol git-msgraph git-protonmail\n```\n\n(Thanks to [@IsaacOscar](https://github.com/IsaacOscar) for adding support for OpenSUSE Tumbleweed!)\n\n#### Nix/NixOS\n\nOn NixOS or a platform running the Nix package manager, one can install the `git-credential-email` meta package or an individual helper package. For example to install the meta package in an interactive shell environment, run:\n\n```bash\nnix-shell -p git-credential-email\n```\n\n(Thanks to [@sephalon](https://github.com/sephalon) for adding support for NixOS!)\n\n### macOS\n\n[Install Homebrew](https://brew.sh/). Then run the following to add the brew tap and install the helpers:\n\n```bash\nbrew tap adityagarg8/git-credential-email\nbrew install git-credential-gmail git-credential-outlook git-credential-yahoo git-credential-aol git-msgraph git-protonmail\n```\n\n### Windows\n\nPrecompiled binaries for Windows are available. You can download the zip containing them from [here](https://github.com/AdityaGarg8/git-credential-email/releases/latest). Extract all the contents of the zip [in your path](https://superuser.com/a/284351/62691). `%ProgramFiles%\\Git\\mingw64\\libexec\\git-core` is also a part of `%PATH%` when git is installed on Windows. As an example, to install `git-credential-gmail` on Windows over there, open **Command Prompt as administrator** and run the following:\n\n```batch\ncurl -L -o %temp%\\cred.zip https://github.com/AdityaGarg8/git-credential-email/releases/latest/download/git-credential-gmail_win64.zip\ntar -xf %temp%\\cred.zip -C \"%ProgramFiles%\\Git\\mingw64\\libexec\\git-core\"\n```\n\n## Setting up OAuth 2.0 client credentials\n\n**You can skip this section if you are using Proton Mail**\n\nIn order to use OAuth2.0, you need to provide an OAuth 2.0 `client_id` and a `client_secret` (secret not needed in Outlook) to allow the helper to authenticate with email servers on your behalf.\n\nIf not configured, it will use Thunderbird's `client_id` and `client_secret` by default.\n\nThe helpers include the client credentials of the following popular email clients:\n\n- Thunderbird\n- GNOME Evolution (only available for Gmail, Outlook and Yahoo)\n- GNOME Online Accounts (only available for Gmail and Outlook)\n\nIn order to set the client credentials of your choice, run (taking `git credential-gmail` as an example):\n\n```bash\ngit credential-gmail --set-client\n```\n\nHere you can either choose from the pre-configured client credentials, or choose to use your own registered client. Instructions for registering your own client are given below:\n\n- Gmail: You can register a [Google API desktop app client](https://developers.google.com/identity/protocols/oauth2/native-app) and use its client credentials.\n- Outlook: If you are part of the Microsoft 365 Developer Programme or have an Azure account (including free accounts), you can create your own app registration in the [Entra admin centre](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app). Make sure you also set a **Redirect URI**, since in case of Outlook, you also need to specify that when setting the client. It is also recommended to enable device flow for your client if you want to use the `--device` option. If you cannot create your own app registration, use client credentials of any email client.\n- Yahoo and AOL: Currently no option to register your own client is available. You will have to use client credentials of any email client.\n\nIn case you want to delete the client credentials you stored and go back to the default behaviour, run:\n\n```bash\ngit credential-gmail --delete-client\n```\n\n## Authenticating with your email provider\n\nNow we need to authenticate with our email provider to get the necessary tokens to authenticate using OAuth2.0.\n\n**Note: Except for `git-msgraph` and `git-protonmail`, make sure you have atleast version 2.1800 of perl's [Authen::SASL](https://metacpan.org/dist/Authen-SASL) library in order to be able to use OAuth2.0. You can run `cpan install Authen::SASL` to install the latest version of this library. `git-msgraph` and `git-protonmail` do not require this library.**\n\n### Gmail\n\n- First of all we need to authenticate with our Gmail credentials and get a refresh token. For that run:\n\n  ```bash\n  git credential-gmail --authenticate\n  ```\n\n- By default it opens a browser window dedicated for authentication. You can choose to use your own browser by adding `--external-auth`. This shall be useful in case of systems without a GUI as well, where you can use the browser of another system:\n\n  ```bash\n  git credential-gmail --authenticate --external-auth\n  ```\n\n### Outlook\n\n#### Using the SMTP server\n\nMicrosoft Outlook accounts can send emails using two methods. First is their SMTP server, which is similar to what most email providers use. Second is Microsoft Graph API. These instructions are in case you want to use the SMTP server.\n\n**Note: It is recommended to use atleast git 2.50 for threads to properly work with Outlook's SMTP server. If you are using an older version of git, then its better to use [Microsoft Graph API](#using-microsoft-graph-api) using `git-msgraph` for threads to work properly.**\n\n- Similar to Gmail, we need to get a refresh token for Outlook as well. For that run:\n\n  ```bash\n  git credential-outlook --authenticate\n  ```\n\n- Similarly, you can also choose to use your own browser by adding `--external-auth`:\n\n  ```bash\n  git credential-outlook --authenticate --external-auth\n  ```\n\n- You can also add `--device` to authenticate on another device like in case of systems without a GUI. This feature is exclusive to Outlook.\n\n  ```bash\n  git credential-outlook --authenticate --device\n  ```\n\n#### Using Microsoft Graph API\n\nMicrosoft Graph API can be used instead of Outlook's SMTP server to send emails. Microsoft Graph API tends to be faster than SMTP. If you want to use Microsoft Graph API to send emails, follow these instructions.\n\n- Similar to SMTP helper, we need to get a refresh token for Microsoft Graph API as well. For that run:\n\n  ```bash\n  git msgraph --authenticate\n  ```\n\n- Similarly, you can also choose to use your own browser by adding `--external-auth`:\n\n  ```bash\n  git msgraph --authenticate --external-auth\n  ```\n\n- You can also add `--device` to authenticate on another device like in case of systems without a GUI. This feature is exclusive to Outlook.\n\n  ```bash\n  git msgraph --authenticate --device\n  ```\n\n**Note:** When sending/cc'ing an email to yourself, Microsoft Graph may incorrectly re-encode your message when you receive it, in case you are using special characters like non breaking space. However, the email stored in your *Sent* folder and received by *other email addresses* should be correct, so you do not need to worry at all!\n\n### Yahoo\n\n- Yahoo is quite similar to Gmail. We need to authenticate with our Yahoo credentials and get a refresh token. For that run:\n\n  ```bash\n  git credential-yahoo --authenticate\n  ```\n\n- `--external-auth` is also supported:\n\n  ```bash\n  git credential-yahoo --authenticate --external-auth\n  ```\n\n### AOL\n\n- AOL is same as Yahoo. We need to authenticate with our AOL credentials and get a refresh token. For that run:\n\n  ```bash\n  git credential-aol --authenticate\n  ```\n\n- `--external-auth` is also supported:\n\n  ```bash\n  git credential-aol --authenticate --external-auth\n  ```\n\n### Proton Mail\n\n- You can authenticate with your Proton Mail credentials by running:\n\n  ```bash\n  git protonmail --authenticate\n  ```\n\n- If `--authenticate` does not work, you try adding `--alternate-auth`:\n\n  ```bash\n  git protonmail --authenticate --alternate-auth\n  ```\n\n#### Solving CAPTCHA while authenticating in Proton Mail\n\nThere is a high chance that you will be asked to solve a CAPTCHA when you try to authenticate for Proton Mail. The on-screen instructions should be followed while solving the CAPTCHA.\n\nFor an easier CAPTCHA solving experience, you can install either `PyQt6-WebEngine` or `OpenCV`.\n\n`PyQt6-WebEngine` will open a dedicated broswer window for solving CAPTCHA for you to solve and send the solved CAPTCHA to the credential helper. It occupies around 100-200MBs depending on your OS.\n\n`OpenCV` is more advanced and can automatically solve the CAPTCHA 99% times, without you needing to solve it at all! But it also occupies around 600MBs. An alternate is `opencv-python-headless` available using `pip` that is lighter, and is the best option for headless systems. It is not available if you are using apt/dnf/brew to install the helper. If you are using a [Windows binary](#windows), `opencv-python-headless` is bundled by default.\n\nI would recommend installing `PyQt6-WebEngine` if you are on a system with GUI and `OpenCV` for headless systems.\n\nYou can install them by running (modify the commands accordingly if you want to install only one of them):\n\n- For all platforms: `pip install PyQt6-WebEngine opencv-python`\n- If you have a headless system: `pip install opencv-python-headless` (PyQt6-WebEngine is a GUI app, so will not work in headless systems)\n- Ubuntu/Debian: `sudo apt-get install -y python3-pyqt6.qtwebengine python3-opencv`\n- Fedora: `sudo dnf install -y python-pyqt6-webengine python-opencv`\n- macOS: `brew install pyqt@6 opencv`\n\n## Usage\n\n- Once authenticated, the refresh token gets saved in your keyring. You can run your helper to confirm the same. For example, for **Gmail** run `git credential-gmail`. It's output should now show an access token.\n- For **Proton Mail** users instead of a refresh token, a session file is stored in your `$HOME` folder and is encrypted with a random key. That key is stored in your keyring. To check if its authenticated, check for presence of `.git-protonmail.pickle` file in your `$HOME` folder. Note that this file may be hidden by default on Linux and macOS.\n\n- Now run:\n\n  ```bash\n  git config --global --edit\n  ```\n\n  And add the following at the end to setup `git send-email`:\n\n### Gmail\n\n  ```config\n  [credential \"smtp://smtp.gmail.com:465\"]\n        helper = \n        helper = gmail\n  [sendemail]\n        smtpEncryption = ssl\n        smtpServer = smtp.gmail.com\n        smtpUser = someone@gmail.com # Replace this with your email address\n        smtpServerPort = 465\n        smtpAuth = OAUTHBEARER\n        from = Your Name \u003csomeone@gmail.com\u003e # Replace this with your name and email address\n  ```\n\n### Outlook\n\n#### Using the SMTP server\n\n  ```config\n  [credential \"smtp://smtp.office365.com:587\"]\n        helper = \n        helper = outlook\n  [sendemail]\n        smtpEncryption = tls\n        smtpServer = smtp.office365.com\n        smtpUser = someone@outlook.com # Replace this with your email address\n        smtpServerPort = 587\n        smtpAuth = XOAUTH2\n        from = Your Name \u003csomeone@outlook.com\u003e # Replace this with your name and email address\n  ```\n\n#### Using Microsoft Graph API\n\n  ```config\n  [sendemail]\n        sendmailCmd = git-msgraph\n        from = someone@outlook.com # Replace this with your email address\n  ```\n\n### Yahoo\n\n  ```config\n  [credential \"smtp://smtp.mail.yahoo.com:465\"]\n        helper = \n        helper = yahoo\n  [sendemail]\n        smtpEncryption = ssl\n        smtpServer = smtp.mail.yahoo.com\n        smtpUser = someone@yahoo.com # Replace this with your email address\n        smtpServerPort = 465\n        smtpAuth = OAUTHBEARER\n        from = Your Name \u003csomeone@yahoo.com\u003e # Replace this with your name and email address\n  ```\n\n### AOL\n\n  ```config\n  [credential \"smtp://smtp.aol.com:465\"]\n        helper = \n        helper = aol\n  [sendemail]\n        smtpEncryption = ssl\n        smtpServer = smtp.aol.com\n        smtpUser = someone@aol.com # Replace this with your email address\n        smtpServerPort = 465\n        smtpAuth = OAUTHBEARER\n        from = Your Name \u003csomeone@aol.com\u003e # Replace this with your name and email address\n  ```\n\n### Proton Mail\n\n  ```config\n  [sendemail]\n        sendmailCmd = git-protonmail\n        from = someone@proton.me # Replace this with your email address. If you have multiple addresses (seen in paid accounts), use the address you want to send from.\n  ```\n\n## Deleting the stored authentication details\n\nIn case you want to delete the refresh token, that was stored by the helper, as mentioned [here](#authenticating-with-your-email-provider), simply run (taking `git credential-gmail` as an example):\n\n```bash\ngit credential-gmail --delete-token\n```\n\nFor **Proton Mail**, you need to delete both the session file and the key that encrypted it. This command will help you for that:\n\n```bash\ngit protonmail --delete-session\n```\n\n## Troubleshooting\n\nIn case authentication fails:\n\n1. Try force refreshing the access token by running (taking `git credential-gmail` as an example):\n\n   ```bash\n   git credential-gmail --force-refresh-token\n   ```\n\n2. If `--force-refresh-token` does not work, try [authenticating again](#authenticating-with-your-email-provider).\n\n## References and useful links:\n\n- \u003chttps://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py\u003e (As a skeleton for all helpers and also Gmail support).\n- \u003chttps://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow\u003e (For Outlook).\n- \u003chttps://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-device-code\u003e (For adding device flow support to Outlook).\n- \u003chttps://learn.microsoft.com/en-us/graph/api/user-sendmail\u003e (For Microsoft Graph API)\n- \u003chttps://developer.yahoo.com/oauth2/guide/flows_authcode\u003e (For Yahoo).\n- \u003chttps://github.com/opulentfox-29/protonmail-api-client\u003e (For Proton Mail).\n- \u003chttps://github.com/AdityaGarg8/git-credential-email/releases/tag/debian\u003e (GitHub release that hosts the apt repo).\n- \u003chttps://github.com/AdityaGarg8/git-credential-email/releases/tag/archlinux\u003e (GitHub release that hosts the pacman repo).\n- \u003chttps://copr.fedorainfracloud.org/coprs/adityagarg8/git-credential-email/\u003e (Copr repo).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityagarg8%2Fgit-credential-email","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadityagarg8%2Fgit-credential-email","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityagarg8%2Fgit-credential-email/lists"}