Skip to main content

A simple Python API client for Gmail.

Project description

# simple-gmail

A simple Gmail API client in Python.

Current Supported Behavior:
* Sending html messages
* Sending messages with attachments
* Sending messages with your Gmail account signature
* Retrieving messages with the full suite of Gmail's search capabilities

## Usage
### Send a simple message:
```python
from simplegmail import Gmail

gmail = Gmail() # will open a browser window to ask you to log in and authenticate

params = {
"to": "you@youremail.com",
"sender": "me@myemail.com",
"subject": "My first email",
"msg_html": "<h1>Woah, my first email!</h1><br />This is an HTML email.",
"msg_plain": "Hi\nThis is a plain text email.",
"signature": True # use my account signature
}
gmail.send_message(**params) # equivalent to send_message(to="you@youremail.com", sender=...)
```

### Send a message with attachments, cc, bcc fields:
```python
from simplegmail import Gmail

gmail = Gmail() # will open a browser window to ask you to log in and authenticate

params = {
"to": "you@youremail.com",
"sender": "me@myemail.com",
"cc": ["bob@bobsemail.com"],
"bcc": ["marie@gossip.com", "hidden@whereami.com"],
"subject": "My first email",
"msg_html": "<h1>Woah, my first email!</h1><br />This is an HTML email.",
"msg_plain": "Hi\nThis is a plain text email.",
"attachments": ["path/to/something/cool.pdf", "path/to/image.jpg", "path/to/script.py"],
"signature": True # use my account signature
}
gmail.send_message(**params) # equivalent to send_message(to="you@youremail.com", sender=...)
```

It couldn't be easier!

### Retrieving messages:
```python
from simplegmail import Gmail

gmail = Gmail() # will open a browser window to ask you to log in and authenticate

# Unread messages in your inbox
messages = gmail.get_unread_inbox()

# Starred messages
messages = gmail.get_starred_messages

# ...and many more easy to use functions...

# Print them out!
for each message in messages:
print("To: " + message['To'])
print("From: " + message['From'])
print("Subject: " + message['Subject'])
print("Date: " + message['Date'])
print("Preview: " + message['Snippet'])

# print("Message Body: " + message['Message Body'])
```

### Retrieving messages (advanced, with queries!):
```python
from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail() # will open a browser window to ask you to log in and authenticate

# Unread messages in inbox with label "Work"
messages = gmail.get_unread_inbox(label_ids=["Work"])

# For even more control use queries:
# Messages that are: newer than 2 days old, unread, labeled "Work" or both "Homework" and "CS"
query_params = {
"newer_than": (2, "day"),
"unread": True,
"labels":[["Work"], ["Homework", "CS"]]
}

messages = gmail.get_messages(query=construct_query(query_params))

# We could have also accomplished this with
# messages = gmail.get_unread_messages(query=construct_query(newer_than=(2, "day"), labels=[["Work"], ["Homework", "CS"]]))
# There are many, many different ways of achieving the same result with search.
```

### Retrieving messages (more advanced, with more queries!):
```python
from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail() # will open a browser window to ask you to log in and authenticate

# For even more control use queries:
# Messages that are either:
# newer than 2 days old, unread, labeled "Work" or both "Homework" and "CS"
# or
# newer than 1 month old, unread, labeled "Top Secret", but not starred.

# Construct our two queries separately
query_params_1 = {
"newer_than": (2, "day"),
"unread": True,
"labels":[["Work"], ["Homework", "CS"]]
}

query_params_2 = {
"newer_than": (1, "month"),
"unread": True,
"labels": ["Top Secret"],
"starred": True,
"exclude_starred": True
}

# construct_query() will create both query strings and "or" them together.
messages = gmail.get_messages(query=construct_query(query_params_1, query_params_2))
```

For more on what you can do with queries, read the docstring for `construct_query()` in `query.py`.

## Feedback
If there is functionality you'd like to see added, or any bugs in this project, please let me know by posting an issue or submitting a pull request!


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

simplegmail-0.0.1.tar.gz (10.9 kB view hashes)

Uploaded Source

Built Distribution

simplegmail-0.0.1-py3-none-any.whl (11.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page