# Email Monitor
Email Monitor is a Python module designed for monitoring and searching emails using the IMAP protocol. It is particularly useful for tasks such as OTP code scraping for web automation, email parsing, and email notifications.
This module is primarily focused on Gmail using OAuth2 for authentication, but it can also work with other IMAP email providers. It is currently in beta, so please report any bugs or issues you encounter, I would greatly appreciate it!
## Installation
You can install the Email Monitor module using pip:
```bash
pip install email-monitor
```
## What is this module?
The Email Monitor module is a Python library that enables you to efficiently search, parse, and monitor emails in your mailbox. By providing an intuitive interface for email handling, this module simplifies the process of obtaining specific information from your emails, such as OTP codes, notifications, or important updates.
## Use Cases
Some of the key use cases for this module include:
- **Automatically retrieving OTP codes** sent to your email for web automation tasks
- **Parsing email content** to extract relevant data or notifications
- **Monitoring your mailbox for specific emails**, such as those containing a particular subject, sender, or content
## Supported IMAP Providers
Email Monitor is primarily designed to work with Gmail using OAuth2 authentication, but it can also support other IMAP email providers. To set up Gmail OAuth2 authentication, follow these steps:
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Navigate to "APIs & Services" > "Library" and enable the "Gmail API"
4. Navigate to "APIs & Services" > "Credentials" and create a new "OAuth 2.0 Client ID"
5. Download the `credentials.json` file for your newly created OAuth 2.0 client
## Example
Here's a quick example of how to use the Email Monitor module:
```python
from email_monitor import EmailMonitor
import re
monitor = EmailMonitor(credentials_file="credentials.json")
email = monitor.search_mail(
query={
"subject": "Your OTP Code",
"from": "noreply@example.com",
"text": re.compile("OTP: \d{6}")
},
wait_for_match=True,
unread=True,
labels=["INBOX"],
delay=10
)
print(email)
```
Take a look at the [examples](./examples/) folder for more examples of how to use this module.
## Search Mail Parameters
The `search_mail` function has several parameters that can be used to customize your search:
- `query` (dict): A dictionary containing the search query. The keys are the search parameters and the values are the search terms. Regex is supported.
Example: `{"subject": "Hello", "from": "John Doe", "to": "myOtherMail@gmail.com", "text": re.compile("Hello World")}`
- `wait_for_match` (bool): If set to True, the function will wait for a new email to match the query and return it.
- `unread` (bool): If set to True, the function will search for emails that have already been read.
- `labels` (list): A list of labels to search for. Only works with Gmail.
- `delay` (int): The delay in seconds between each search if `wait_for_match` is set to True.
## Contributing
Contributions are welcome! Feel free to submit pull requests with bug fixes or new features. Check out the [contributing guidelines](./CONTRIBUTING.md) for more information.
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
## Contact Me
If you have any questions or suggestions, feel free to reach out to me:
- GitHub: [glizzykingdreko](https://github.com/glizzykingdreko)
- Medium: [glizzykingdreko](https://medium.com/@glizzykingdreko)
- Twitter: [glizzykingdreko](https://twitter.com/glizzykingdreko)
- Email: glizzykingdreko@protonmail.com
Raw data
{
"_id": null,
"home_page": "https://github.com/glizzykingdreko/email_monitor",
"name": "email-monitor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "glizzykingdreko",
"author_email": "glizzykingdreko@protonmail.com",
"download_url": "",
"platform": null,
"description": "# Email Monitor\n\n\n\n\nEmail Monitor is a Python module designed for monitoring and searching emails using the IMAP protocol. It is particularly useful for tasks such as OTP code scraping for web automation, email parsing, and email notifications. \n\nThis module is primarily focused on Gmail using OAuth2 for authentication, but it can also work with other IMAP email providers. It is currently in beta, so please report any bugs or issues you encounter, I would greatly appreciate it!\n\n## Installation\n\nYou can install the Email Monitor module using pip:\n```bash\npip install email-monitor\n```\n\n## What is this module?\n\nThe Email Monitor module is a Python library that enables you to efficiently search, parse, and monitor emails in your mailbox. By providing an intuitive interface for email handling, this module simplifies the process of obtaining specific information from your emails, such as OTP codes, notifications, or important updates.\n\n## Use Cases\n\nSome of the key use cases for this module include:\n\n- **Automatically retrieving OTP codes** sent to your email for web automation tasks\n- **Parsing email content** to extract relevant data or notifications\n- **Monitoring your mailbox for specific emails**, such as those containing a particular subject, sender, or content\n\n## Supported IMAP Providers\n\nEmail Monitor is primarily designed to work with Gmail using OAuth2 authentication, but it can also support other IMAP email providers. To set up Gmail OAuth2 authentication, follow these steps:\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select an existing one\n3. Navigate to \"APIs & Services\" > \"Library\" and enable the \"Gmail API\"\n4. Navigate to \"APIs & Services\" > \"Credentials\" and create a new \"OAuth 2.0 Client ID\"\n5. Download the `credentials.json` file for your newly created OAuth 2.0 client\n\n## Example\n\nHere's a quick example of how to use the Email Monitor module:\n\n```python\nfrom email_monitor import EmailMonitor\nimport re\n\nmonitor = EmailMonitor(credentials_file=\"credentials.json\")\nemail = monitor.search_mail(\n query={\n \"subject\": \"Your OTP Code\",\n \"from\": \"noreply@example.com\",\n \"text\": re.compile(\"OTP: \\d{6}\")\n },\n wait_for_match=True,\n unread=True,\n labels=[\"INBOX\"],\n delay=10\n)\nprint(email)\n```\nTake a look at the [examples](./examples/) folder for more examples of how to use this module.\n\n## Search Mail Parameters\n\nThe `search_mail` function has several parameters that can be used to customize your search:\n\n- `query` (dict): A dictionary containing the search query. The keys are the search parameters and the values are the search terms. Regex is supported.\n Example: `{\"subject\": \"Hello\", \"from\": \"John Doe\", \"to\": \"myOtherMail@gmail.com\", \"text\": re.compile(\"Hello World\")}`\n\n- `wait_for_match` (bool): If set to True, the function will wait for a new email to match the query and return it.\n\n- `unread` (bool): If set to True, the function will search for emails that have already been read.\n\n- `labels` (list): A list of labels to search for. Only works with Gmail.\n\n- `delay` (int): The delay in seconds between each search if `wait_for_match` is set to True.\n\n## Contributing\n\nContributions are welcome! Feel free to submit pull requests with bug fixes or new features. Check out the [contributing guidelines](./CONTRIBUTING.md) for more information.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## Contact Me\n\nIf you have any questions or suggestions, feel free to reach out to me:\n\n- GitHub: [glizzykingdreko](https://github.com/glizzykingdreko)\n- Medium: [glizzykingdreko](https://medium.com/@glizzykingdreko)\n- Twitter: [glizzykingdreko](https://twitter.com/glizzykingdreko)\n- Email: glizzykingdreko@protonmail.com\n",
"bugtrack_url": null,
"license": "",
"summary": "A versatile IMAP mail monitoring module with Gmail API support, regex queries, and flexible search options",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/glizzykingdreko/email_monitor"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4b94980f520d1d7b99d3ae29459fc509ca3487b8800c29547ded3f32cd856485",
"md5": "f4fce82c98f03a5ef77a596c06997634",
"sha256": "9f109230421d3fdab44250289ac5eec69bbc2fad8ae34813b865024047c0a263"
},
"downloads": -1,
"filename": "email_monitor-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4fce82c98f03a5ef77a596c06997634",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9686,
"upload_time": "2023-08-05T17:46:48",
"upload_time_iso_8601": "2023-08-05T17:46:48.345272Z",
"url": "https://files.pythonhosted.org/packages/4b/94/980f520d1d7b99d3ae29459fc509ca3487b8800c29547ded3f32cd856485/email_monitor-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-05 17:46:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "glizzykingdreko",
"github_project": "email_monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "email-monitor"
}
JSON
