https://github.com/loadsmart/gmail-wrapper
📧 Because scrapping Gmail data doesn't have to be a pain
https://github.com/loadsmart/gmail-wrapper
Last synced: about 1 year ago
JSON representation
📧 Because scrapping Gmail data doesn't have to be a pain
- Host: GitHub
- URL: https://github.com/loadsmart/gmail-wrapper
- Owner: loadsmart
- License: mit
- Created: 2019-08-20T17:35:11.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-07-31T18:50:22.000Z (almost 2 years ago)
- Last Synced: 2025-03-28T10:47:32.665Z (about 1 year ago)
- Language: Python
- Homepage:
- Size: 106 KB
- Stars: 30
- Watchers: 50
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Gmail Wrapper
[](https://circleci.com/gh/loadsmart/gmail-wrapper/tree/master)
Because scrapping Gmail data doesn't have to be a [pain](https://googleapis.github.io/google-api-python-client/docs/dyn/gmail_v1.html).
## Installing
```sh
pip install gmail-wrapper
```
## Developing
Create your [venv](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments)
```sh
virtualenv .venv
source .venv/bin/activate
```
Then you can install the dependencies
```sh
pip install -e .
```
## Testing
Simply run
```sh
make test
```
## Basic Usage
- Setup the client
```python
from gmail_wrapper import GmailClient
email_account = "john.doe@gmail.com"
credentials_string = "{...}" # You must generate this on your Google account
scopes = [GmailClient.SCOPE_READONLY]
client = GmailClient(email_account, secrets_json_string=credentials_string, scopes=scopes)
```
- Fetch messages
```python
import sys
query = "filename:pdf label:friends" # Check Gmail query docs: https://support.google.com/mail/answer/7190
messages = client.get_messages(query=query, limit=10)
for message in messages:
print("-- MESSAGE {} --".format(message.id))
print("SUBJECT: {}".format(message.subject))
print("DATE: {}".format(message.date))
for attachment in message.attachments:
print("\t-- ATTACHMENT {} --".format(attachment.id))
print("\t\tFILENAME: {}".format(attachment.filename))
print("\t\tDECODED SIZE: {}".format(sys.getsizeof(attachment.content)))
```
- Modify message labels
If a single message:
```python
message_id = "..."
message = client.get_message(message_id)
print(message.labels) # ["foo", "bar"]
message.modify(add_labels=["processed"], remove_labels=["foo"]) # Beware that you'll need proper scopes
print(message.labels) # ["bar", "processed"]
```
If multiple messages:
```python
message_ids = ["...", "..."]
message = client.modify_multiple_messages(message_ids, ["processed"], remove_labels=["foo"])
```
- Archive a message
```python
message.archive() # Beware that you'll need proper scopes
```
- Send message
```python
content = '''
Hey there
I am using gmail-wrapper lib!
'''
message = client.send(
subject="You will like it",
html_content=content,
to="thanos@loadsmart.com",
cc=["iron.man@loadsmart.com", "spider.man@loadsmart.com"],
bcc=["wolverine@loadsmart.com"]
) # Beware that you'll need proper scopes
print(message) # Gmail message: ABC123
```
- Reply message
```python
message_id = "..."
message = client.get_message(message_id)
reply = '''
I am out for vacation, will return Jan 14.
If it is really important, you can call me, but think twice.
'''
response = message.reply(reply)
```
- Handle exceptions
Exceptions are part of every developer day-to-day. You may want to handle exceptions as follows:
```python
from gmail_wrapper.exceptions import (
MessageNotFoundError,
AttachmentNotFoundError,
GmailError,
)
try:
do_something()
except MessageNotFoundError as e:
print(f"There is no message! {e}")
except AttachmentNotFoundError as e:
print(f"There is no attachment! {e}")
except GmailError as e:
print(f"Google servers are burning! {e}")
```
## Disclaimer
Gmail is a trademark of Google. This open-source project is **not** an official library nor has any endorsement of Google.