EZGmail

https://ezgmail.readthedocs.io/en/latest/
Admin
EZGmail is a Pythonic interface to the Gmail API that allows developers to easily read, search,...
Tokens:3,557
Snippets:32
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize EZGmail

Source: https://ezgmail.readthedocs.io/en/latest

Import the library and initialize with custom credential and token files.

```python
>>> import ezgmail
```

```python
>>> ezgmail.init(tokenFile='token.json', credentialsFile='credentials.json')
```

--------------------------------

### ezgmail.init

Source: https://ezgmail.readthedocs.io/en/latest

Initializes the Gmail service and authenticates the user.

```APIDOC
## ezgmail.init(userId='me', tokenFile='token.json', credentialsFile='credentials.json', raiseException=True)

### Description
Initializes the Gmail service. This function populates the SERVICE_GMAIL global variable and sets the EMAIL_ADDRESS. If the token file does not exist, it triggers the browser-based login flow.

### Parameters
- **userId** (str) - Optional - The user ID, defaults to 'me'.
- **tokenFile** (str) - Optional - Path to the token file, defaults to 'token.json'.
- **credentialsFile** (str) - Optional - Path to the credentials file, defaults to 'credentials.json'.
- **raiseException** (bool) - Optional - Whether to raise exceptions, defaults to True.
```

--------------------------------

### Accessing and Downloading Email Attachments

Source: https://ezgmail.readthedocs.io/en/latest

Demonstrates searching for email threads, inspecting attachment details, and downloading specific or all attachments to the local filesystem.

```python
>>> import ezgmail
>>> threads = ezgmail.search('See the attached files')
>>> threads[0].messages[0].attachments
>>> import pprint
>>> pprint.pprint(threads[0].messages[0].attachments)
{'a.png': {'id': 'ANGjdJ8eLDbjBpFTfvpuQ2HfR_iwp59XLUIl-IHW8eJcexMsxBYoPCZAXcX16rnqcbJZTknF5r3GmnM1W9n4vAE1oiVgUa4S4zBmNs7rd5PzFwLjO2vU3hp3_9SEZv-KBqVxi9nuNjarxhFqp3mxw6E5mqEYmFOYtT7Gx6CZbLaJuUox9GaWu-W9B4-XPDjwKkEfCdJ21FlOl-CsC6isZgD2Vh-ghh1haZN_2sifccznLv61ZW_KmqPKFcV1j7cXMQVqWU7bkgdH8do4Msc3QsG2ly_PNRid4-7gihsXaLI1ko_j3LSvsoLHFP3edhxh6YKQ2OdMhyZh5lqjmfT1TXgSo7hY16P_ScDO5MnWvmKscf_Hm5y5D4DHfwOq4--Otivoq2WVkVucVUJBkAoB',
           'size': 833609},
 'b.png': {'id': 'ANGjdJ_WYMmPmy2Dd2VBgvVoLAd1p3ARxGXKIzVfKqAiLhvKSBmEowYqFCdHbMJYlDZy4IWBGLg0eQCllMI0icqamM7vfMxBW2irJVogLM6SUT9cIcJFMSF7UhzU2I26bho086J7NjnX5u4kqYj_LHchowO56vTdKLRRsaJ2gfW0esz3cDFZzvthdR4wyBKEIeCJv7OJmFiaJIRf9f1KmFfKPLo9GZSyD2RMXdd6Qa2M3uN9pgT6sZ-OQx3e6aNDAKWh5GCeSiuIt_Z7GsDCdzVJjakMJx5FRFhp5zIck0p04AHnYhKfy1BipWmf7G-DAKzgJHAhFimBVUIBeFsHrqEGxDlevD7lK4ZBeb8cluSmYyEsRkSPSMYMlp-x1GVw25gqMnMVkGMKPfwj38iB',
           'size': 335911}}
>>> threads[0].messages[0].downloadAttachment('a.png') # Download to current working directory.
>>> threads[0].messages[0].downloadAttachment('b.png', '/path/to/save/in')
>>> threads[0].messages[0].downloadAllAttachments() # Easier way to save all attachments.
```

--------------------------------

### ezgmail.summary

Source: https://ezgmail.readthedocs.io/en/latest

Prints a summary of Gmail objects.

```APIDOC
## ezgmail.summary(gmailObjects, printInfo=True)

### Description
Prints a summary of the provided GmailThread or GmailMessage objects.

### Parameters
- **gmailObjects** (list) - Required - List of GmailThread or GmailMessage objects.
- **printInfo** (bool) - Optional - Whether to print the info, defaults to True.
```

--------------------------------

### Check Login Status

Source: https://ezgmail.readthedocs.io/en/latest

Verify the currently logged-in email address and authentication status.

```python
>>> ezgmail.EMAIL_ADDRESS
'test.sweigart@gmail.com'
>>> ezgmail.LOGGED_IN
True
```

--------------------------------

### downloadAllAttachments()

Source: https://ezgmail.readthedocs.io/en/latest

Downloads all attachments associated with the GmailMessage object.

```APIDOC
## downloadAllAttachments()

### Description
Downloads all attachments present in the GmailMessage object to the current working directory.
```

--------------------------------

### Trash Threads

Source: https://ezgmail.readthedocs.io/en/latest

Move email threads to the Trash folder.

```python
>>> import ezgmail
>>> threads = ezgmail.search('mancala')
>>> threads[0].trash()  # Move the entire first thread to the Trash folder.
```

--------------------------------

### Send HTML Email

Source: https://ezgmail.readthedocs.io/en/latest

Send an email formatted with HTML by setting the mimeSubtype parameter.

```python
>>> ezgmail.send('recipient@example.com', 'Subject Line', '<strong>Hello</strong>, this is the <em>body</em> of the message.', mimeSubtype='html')
```

--------------------------------

### Manage Labels

Source: https://ezgmail.readthedocs.io/en/latest

Add or remove the UNREAD label from threads.

```python
>>> import ezgmail
>>> unreadThreads = ezgmail.unread()
>>> ezgmail.removeLabel(unreadThreads, 'UNREAD') # Also marks threads as read.
>>> ezgmail.addLabel(unreadThreads, 'UNREAD') # Marks them as unread again.
>>> # Or you can do:
>>> for unreadThread in unreadThreads:
...     unreadThread.removeLabel(unreadThreads, 'UNREAD') # Mark the individual GmailThread objects as read.
```

--------------------------------

### Send Email

Source: https://ezgmail.readthedocs.io/en/latest

Send a basic plaintext email to a recipient.

```python
>>> ezgmail.send('recipient@example.com', 'Subject Line', 'Hello, this is the body of the message.')
```

--------------------------------

### GmailMessage.downloadAllAttachments

Source: https://ezgmail.readthedocs.io/en/latest

Downloads all attachments from a specific Gmail message to a local directory.

```APIDOC
## GmailMessage.downloadAllAttachments(downloadFolder='.', overwrite=True)

### Description
Downloads all of the attachments in this message to the local folder specified by `downloadFolder`.

### Parameters
- **downloadFolder** (str) - Optional - The local directory path to save attachments. Defaults to '.'
- **overwrite** (bool) - Optional - If True, existing local files will be overwritten by attachments with the same filename. Defaults to True
```

--------------------------------

### downloadAttachment(filename, downloadFolder)

Source: https://ezgmail.readthedocs.io/en/latest

Downloads a specific attachment by filename to the current working directory or a specified folder.

```APIDOC
## downloadAttachment(filename, downloadFolder)

### Description
Downloads a specific attachment from the GmailMessage object. If no folder is specified, it defaults to the current working directory.

### Parameters
- **filename** (string) - Required - The name of the attachment file to download.
- **downloadFolder** (string) - Optional - The path to the directory where the file should be saved.
```

--------------------------------

### GmailThread.trash

Source: https://ezgmail.readthedocs.io/en/latest

Moves every message in the thread to the Trash folder.

```APIDOC
## GmailThread.trash()

### Description
Moves every message in this thread to the Trash folder. Messages will be automatically removed in 30 days.
```

--------------------------------

### Search Gmail

Source: https://ezgmail.readthedocs.io/en/latest

Perform searches using standard Gmail query syntax.

```python
>>> ezgmail.search('label:UNREAD')
>>> ezgmail.search('from:al@inventwithpython.com')
>>> ezgmail.search('subject:hello')
>>> ezgmail.search('has:attachment')
```

--------------------------------

### ezgmail.recent

Source: https://ezgmail.readthedocs.io/en/latest

Retrieves a list of recent email threads.

```APIDOC
## ezgmail.recent(maxResults=25, userId='me')

### Description
Returns a list of GmailThread objects for the most recent emails. This is a wrapper for the search function.

### Parameters
- **maxResults** (int) - Optional - Maximum number of results to return, defaults to 25.
- **userId** (str) - Optional - The user ID, defaults to 'me'.
```

--------------------------------

### ezgmail.send

Source: https://ezgmail.readthedocs.io/en/latest

Sends an email via the configured Gmail account.

```APIDOC
## ezgmail.send(recipient, subject, body, attachments=None, sender=None, cc=None, bcc=None, mimeSubtype='plain', threadId=None)

### Description
Sends an email from the authenticated Gmail account.

### Parameters
- **recipient** (str) - Required - Email address of the recipient.
- **subject** (str) - Required - Subject line of the email.
- **body** (str) - Required - Body content of the email.
- **attachments** (list) - Optional - List of file paths to attach.
- **sender** (str) - Optional - Sender email address (often ignored by Gmail).
- **cc** (str) - Optional - CC recipients.
- **bcc** (str) - Optional - BCC recipients.
- **mimeSubtype** (str) - Optional - MIME subtype, defaults to 'plain'.
- **threadId** (str) - Optional - Thread ID to reply to.
```

--------------------------------

### Retrieve and Inspect Unread Threads

Source: https://ezgmail.readthedocs.io/en/latest

Fetch unread email threads and access message attributes like sender, timestamp, subject, and body.

```python
>>> ezgmail.unread()
[<GmailThread len=4 snippet='Quickstart was granted access to your Google Account test.sweigart@gmail.com If you did not grant access, you should check this activity and secure your account. Check activity You received this email'>]

>>> unreadThreads = ezgmail.unread()

>>> unreadThreads
[<GmailThread len=4 snippet='Quickstart was granted access to your Google Account test.sweigart@gmail.com If you did not grant access, you should check this activity and secure your account. Check activity You received this email'>]

>>> thread = unreadThreads[0]

>>> thread.messages
[<ezgmail.GmailMessage object at 0x000002B7F1FD8A90>, <ezgmail.GmailMessage object at 0x000002B7F1FD80B8>, <ezgmail.GmailMessage object at 0x000002B7F1FD8A58>, <ezgmail.GmailMessage object at 0x000002B7F1FD8160>]

>>> thread.messages[0].sender
'Alice Smith <alice@example.com>'

>>> thread.messages[0].timestamp
datetime.datetime(2019, 11, 11, 10, 7, 55)

>>> thread.messages[0].subject
'Good to meet you!'

>>> thread.messages[0].body
"It was good to meetup!\r\n\r\n\r\nWe should hang out again soon.\r\n"
```

--------------------------------

### Mark Threads as Read

Source: https://ezgmail.readthedocs.io/en/latest

Update the read status of threads or messages.

```python
>>> import ezgmail
>>> unreadThreads = ezgmail.unread()
>>> ezgmail.markAsRead(unreadThreads) # Marks all the GmailThread objects in the unreadThreads list as read.
>>> # Or you can do:
>>> for unreadThread in unreadThreads:
...     unreadThread.markAsRead() # Mark the individual GmailThread objects as read.
```

--------------------------------

### ezgmail.search

Source: https://ezgmail.readthedocs.io/en/latest

Searches for email threads based on a query.

```APIDOC
## ezgmail.search(query, maxResults=25, userId='me')

### Description
Returns a list of GmailThread objects that match the provided search query. The query syntax follows standard Gmail search box rules.

### Parameters
- **query** (str) - Required - The search query string.
- **maxResults** (int) - Optional - Maximum number of results to return, defaults to 25.
- **userId** (str) - Optional - The user ID, defaults to 'me'.
```

--------------------------------

### ezgmail.unread

Source: https://ezgmail.readthedocs.io/en/latest

Retrieves a list of unread email threads.

```APIDOC
## ezgmail.unread(maxResults=25, userId='me')

### Description
Returns a list of GmailThread objects for unread emails. This is a wrapper for the search function.

### Parameters
- **maxResults** (int) - Optional - Maximum number of results to return, defaults to 25.
- **userId** (str) - Optional - The user ID, defaults to 'me'.
```

--------------------------------

### GmailMessage.reply

Source: https://ezgmail.readthedocs.io/en/latest

Sends a reply to the last message in the current thread.

```APIDOC
## GmailMessage.reply(body, attachments=None, cc=None, bcc=None, mimeSubtype='plain')

### Description
Sends a reply to the last message in this thread using the provided body and optional metadata.

### Parameters
- **body** (str) - Required - The text content of the reply.
- **attachments** (list) - Optional - A list of file paths to attach.
- **cc** (list) - Optional - A list of email addresses to CC.
- **bcc** (list) - Optional - A list of email addresses to BCC.
- **mimeSubtype** (str) - Optional - The MIME subtype for the message. Defaults to 'plain'.
```

--------------------------------

### ezgmail.removeQuotedParts

Source: https://ezgmail.readthedocs.io/en/latest

Strips quoted reply text from an email body.

```APIDOC
## ezgmail.removeQuotedParts(emailText)

### Description
Returns the text in emailText up to the quoted reply section.

### Parameters
- **emailText** (str) - Required - The raw email body text.
```
Tokens:
Raw