# MailTM Python SDK
[](https://www.gnu.org/licenses/gpl-3.0)
The MailTM Python SDK provides a simple and efficient way to interact with the [Mail.tm API](https://mail.tm), which allows you to create temporary email accounts and manage messages programmatically. This SDK is ideal for automated testing, handling email verifications, and other scenarios where disposable email addresses are useful.
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Creating an Account](#creating-an-account)
- [Fetching Domains](#fetching-domains)
- [Retrieving Messages](#retrieving-messages)
- [Deleting Messages](#deleting-messages)
- [Methods](#methods)
- [Contributing](#contributing)
- [License](#license)
## Introduction
MailTM is a temporary email service that provides disposable email addresses. This SDK allows developers to interact with the MailTM API to create temporary email accounts, retrieve and manage messages, and delete accounts when they are no longer needed.
## Installation
To install the MailTM Python SDK, simply use `pip`:
```bash
pip install mailtm-python
```
To install nightly builds, use the following command:
```bash
pip install git+https://github.com/viperadnan-git/mailtm-python-sdk.git --force-reinstall
```
Alternatively, you can clone the repository and install the dependencies manually:
```bash
git clone https://github.com/viperadnan-git/mailtm-python-sdk.git
cd mailtm-python-sdk
pip install -r requirements.txt
```
## Usage
### Creating an Account
To create a new temporary email account, you can use the `create_account` method. Here's an example:
```python
from mailtm import MailTMClient
# Fetch available domains
domains = MailTMClient.get_domains()
# Create a new account using one of the domains
email_address = f"mytempemail@{domains[0].domain}"
password = "supersecretpassword"
client = MailTMClient.create_account(address=email_address, password=password)
print(f"Account created with email: {client.address}")
```
### Fetching Domains
To fetch the list of available domains that can be used for creating temporary email addresses:
```python
domains = MailTMClient.get_domains()
for domain in domains:
print(f"Domain: {domain.domain}")
```
### Retrieving Messages
After creating an account and authenticating, you can retrieve messages for that account:
```python
# Fetch messages
messages = client.get_messages()
for message in messages:
print(f"From: {message.from_.address}, Subject: {message.subject}")
```
### Deleting Messages
You can delete a specific message by its ID:
```python
message_id = messages[0].id
client.delete_message(message_id)
print(f"Message {message_id} deleted.")
```
## Methods
The following methods are provided by the `MailTMClient` class:
- **`MailTMClient.get_domains(page: int = 1, proxies: Optional[Dict[str, str]] = None) -> List[Domain]`**: Fetch the available domains for creating an account.
Example:
```python
domains = MailTMClient.get_domains(proxies={"http": "http://proxy.example.com:8080"})
for domain in domains:
print(f"Domain: {domain.domain}")
```
- **`MailTMClient.get_domain_by_id(domain_id: str, proxies: Optional[Dict[str, str]] = None) -> Domain`**: Retrieve details of a specific domain by its ID.
Example:
```python
domain = MailTMClient.get_domain_by_id("some-domain-id", proxies={"http": "http://proxy.example.com:8080"})
print(f"Domain: {domain.domain}")
```
- **`MailTMClient.create_account(address: str, password: str, proxies: Optional[Dict[str, str]] = None) -> Account`**: Create a new temporary email account.
Example:
```python
account = MailTMClient.create_account("user@domain.com", "password", proxies={"http": "http://proxy.example.com:8080"})
print(f"Account created with email: {account.address}")
```
- **`MailTMClient.get_token(address: str, password: str) -> TokenResponse`**: Authenticate and obtain a token for an account.
Example:
```python
token_response = MailTMClient.get_token("mytempemail@mail.tm", "supersecretpassword")
print(f"Token: {token_response.token}")
```
- **`MailTMClient.get_account(token: Optional[str] = None) -> Account`**: Get details of the authenticated account.
Example:
```python
account = client.get_account()
print(f"Account: {account.address}")
```
- **`MailTMClient.get_account_by_id(account_id: str) -> Account`**: Get details of an account by its ID.
Example:
```python
account = client.get_account_by_id("some-account-id")
print(f"Account: {account.address}")
```
- **`MailTMClient.delete_account(account_id: str) -> bool`**: Delete an account by its ID.
Example:
```python
success = client.delete_account("some-account-id")
if success:
print("Account successfully deleted.")
```
- **`MailTMClient.get_messages(page: int = 1) -> List[Message]`**: Retrieve messages for the authenticated account.
Example:
```python
messages = client.get_messages()
for message in messages:
print(f"From: {message.from_.address}, Subject: {message.subject}")
```
- **`MailTMClient.get_message_by_id(message_id: str) -> MessageDetail`**: Retrieve a specific message by its ID.
Example:
```python
message_detail = client.get_message_by_id("some-message-id")
print(f"Message from: {message_detail.from_.address}, Subject: {message_detail.subject}")
```
- **`MailTMClient.delete_message(message_id: str) -> bool`**: Delete a specific message by its ID.
Example:
```python
success = client.delete_message("some-message-id")
if success:
print("Message successfully deleted.")
```
- **`MailTMClient.mark_message_as_read(message_id: str) -> MessageDetail`**: Mark a message as read.
Example:
```python
message_detail = client.mark_message_as_read("some-message-id")
print(f"Message read status: {message_detail.seen}")
```
- **`MailTMClient.get_message_source(message_id: str) -> MessageSource`**: Get the raw source of a message.
Example:
```python
message_source = client.get_message_source("some-message-id")
print(f"Message source: {message_source.data}")
```
- **`MailTMClient.get_message_attachments(message_id: str) -> List[Attachment]`**: Get the attachments of a specific message.
Example:
```python
attachments = client.get_message_attachments("some-message-id")
for attachment in attachments:
print(f"Attachment: {attachment.filename}")
```
- **`MailTMClient.get_attachment(message_id: str, attachment_id: str) -> Attachment`**: Get a specific attachment by its ID.
Example:
```python
attachment = client.get_attachment("some-message-id", "some-attachment-id")
print(f"Attachment filename: {attachment.filename}")
```
## Contributing
We welcome contributions to the MailTM Python SDK! If you find a bug or want to add a feature, feel free to open an issue or submit a pull request.
## License
This project is licensed under the GNU General Public License v3 (GPLv3) - see the [LICENSE](./LICENSE) file for details.
---
**Note**: This SDK is designed for use with the MailTM API. Please ensure you use this SDK responsibly and adhere to MailTM's terms of service. Misuse of this SDK for illegal activities is strictly prohibited.
Raw data
{
"_id": null,
"home_page": "https://github.com/viperadnan-git/mailtm-python-sdk",
"name": "mailtm-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Adnan Ahmad",
"author_email": "viperadnan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a4/7e/34e2e3c27fd54d9aa854f7cf3d2a0633df2297c5560cb774ac5bba780036/mailtm_python-0.1.0.tar.gz",
"platform": null,
"description": "# MailTM Python SDK\n\n[](https://www.gnu.org/licenses/gpl-3.0)\n\nThe MailTM Python SDK provides a simple and efficient way to interact with the [Mail.tm API](https://mail.tm), which allows you to create temporary email accounts and manage messages programmatically. This SDK is ideal for automated testing, handling email verifications, and other scenarios where disposable email addresses are useful.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Creating an Account](#creating-an-account)\n - [Fetching Domains](#fetching-domains)\n - [Retrieving Messages](#retrieving-messages)\n - [Deleting Messages](#deleting-messages)\n- [Methods](#methods)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\nMailTM is a temporary email service that provides disposable email addresses. This SDK allows developers to interact with the MailTM API to create temporary email accounts, retrieve and manage messages, and delete accounts when they are no longer needed.\n\n## Installation\n\nTo install the MailTM Python SDK, simply use `pip`:\n\n```bash\npip install mailtm-python\n```\n\nTo install nightly builds, use the following command:\n\n```bash\npip install git+https://github.com/viperadnan-git/mailtm-python-sdk.git --force-reinstall\n```\n\nAlternatively, you can clone the repository and install the dependencies manually:\n\n```bash\ngit clone https://github.com/viperadnan-git/mailtm-python-sdk.git\ncd mailtm-python-sdk\npip install -r requirements.txt\n```\n\n## Usage\n\n### Creating an Account\n\nTo create a new temporary email account, you can use the `create_account` method. Here's an example:\n\n```python\nfrom mailtm import MailTMClient\n\n# Fetch available domains\ndomains = MailTMClient.get_domains()\n\n# Create a new account using one of the domains\nemail_address = f\"mytempemail@{domains[0].domain}\"\npassword = \"supersecretpassword\"\n\nclient = MailTMClient.create_account(address=email_address, password=password)\nprint(f\"Account created with email: {client.address}\")\n```\n\n### Fetching Domains\n\nTo fetch the list of available domains that can be used for creating temporary email addresses:\n\n```python\ndomains = MailTMClient.get_domains()\nfor domain in domains:\n print(f\"Domain: {domain.domain}\")\n```\n\n### Retrieving Messages\n\nAfter creating an account and authenticating, you can retrieve messages for that account:\n\n```python\n# Fetch messages\nmessages = client.get_messages()\nfor message in messages:\n print(f\"From: {message.from_.address}, Subject: {message.subject}\")\n```\n\n### Deleting Messages\n\nYou can delete a specific message by its ID:\n\n```python\nmessage_id = messages[0].id\nclient.delete_message(message_id)\nprint(f\"Message {message_id} deleted.\")\n```\n\n## Methods\n\nThe following methods are provided by the `MailTMClient` class:\n\n- **`MailTMClient.get_domains(page: int = 1, proxies: Optional[Dict[str, str]] = None) -> List[Domain]`**: Fetch the available domains for creating an account.\n \n Example:\n \n ```python\n domains = MailTMClient.get_domains(proxies={\"http\": \"http://proxy.example.com:8080\"})\n for domain in domains:\n print(f\"Domain: {domain.domain}\")\n ```\n\n- **`MailTMClient.get_domain_by_id(domain_id: str, proxies: Optional[Dict[str, str]] = None) -> Domain`**: Retrieve details of a specific domain by its ID.\n \n Example:\n \n ```python\n domain = MailTMClient.get_domain_by_id(\"some-domain-id\", proxies={\"http\": \"http://proxy.example.com:8080\"})\n print(f\"Domain: {domain.domain}\")\n ```\n\n- **`MailTMClient.create_account(address: str, password: str, proxies: Optional[Dict[str, str]] = None) -> Account`**: Create a new temporary email account.\n \n Example:\n \n ```python\n account = MailTMClient.create_account(\"user@domain.com\", \"password\", proxies={\"http\": \"http://proxy.example.com:8080\"})\n print(f\"Account created with email: {account.address}\")\n ```\n\n- **`MailTMClient.get_token(address: str, password: str) -> TokenResponse`**: Authenticate and obtain a token for an account.\n \n Example:\n \n ```python\n token_response = MailTMClient.get_token(\"mytempemail@mail.tm\", \"supersecretpassword\")\n print(f\"Token: {token_response.token}\")\n ```\n\n- **`MailTMClient.get_account(token: Optional[str] = None) -> Account`**: Get details of the authenticated account.\n \n Example:\n \n ```python\n account = client.get_account()\n print(f\"Account: {account.address}\")\n ```\n\n- **`MailTMClient.get_account_by_id(account_id: str) -> Account`**: Get details of an account by its ID.\n \n Example:\n \n ```python\n account = client.get_account_by_id(\"some-account-id\")\n print(f\"Account: {account.address}\")\n ```\n\n- **`MailTMClient.delete_account(account_id: str) -> bool`**: Delete an account by its ID.\n \n Example:\n \n ```python\n success = client.delete_account(\"some-account-id\")\n if success:\n print(\"Account successfully deleted.\")\n ```\n\n- **`MailTMClient.get_messages(page: int = 1) -> List[Message]`**: Retrieve messages for the authenticated account.\n \n Example:\n \n ```python\n messages = client.get_messages()\n for message in messages:\n print(f\"From: {message.from_.address}, Subject: {message.subject}\")\n ```\n\n- **`MailTMClient.get_message_by_id(message_id: str) -> MessageDetail`**: Retrieve a specific message by its ID.\n \n Example:\n \n ```python\n message_detail = client.get_message_by_id(\"some-message-id\")\n print(f\"Message from: {message_detail.from_.address}, Subject: {message_detail.subject}\")\n ```\n\n- **`MailTMClient.delete_message(message_id: str) -> bool`**: Delete a specific message by its ID.\n \n Example:\n \n ```python\n success = client.delete_message(\"some-message-id\")\n if success:\n print(\"Message successfully deleted.\")\n ```\n\n- **`MailTMClient.mark_message_as_read(message_id: str) -> MessageDetail`**: Mark a message as read.\n \n Example:\n \n ```python\n message_detail = client.mark_message_as_read(\"some-message-id\")\n print(f\"Message read status: {message_detail.seen}\")\n ```\n\n- **`MailTMClient.get_message_source(message_id: str) -> MessageSource`**: Get the raw source of a message.\n \n Example:\n \n ```python\n message_source = client.get_message_source(\"some-message-id\")\n print(f\"Message source: {message_source.data}\")\n ```\n\n- **`MailTMClient.get_message_attachments(message_id: str) -> List[Attachment]`**: Get the attachments of a specific message.\n \n Example:\n \n ```python\n attachments = client.get_message_attachments(\"some-message-id\")\n for attachment in attachments:\n print(f\"Attachment: {attachment.filename}\")\n ```\n\n- **`MailTMClient.get_attachment(message_id: str, attachment_id: str) -> Attachment`**: Get a specific attachment by its ID.\n \n Example:\n \n ```python\n attachment = client.get_attachment(\"some-message-id\", \"some-attachment-id\")\n print(f\"Attachment filename: {attachment.filename}\")\n ```\n\n## Contributing\n\nWe welcome contributions to the MailTM Python SDK! If you find a bug or want to add a feature, feel free to open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the GNU General Public License v3 (GPLv3) - see the [LICENSE](./LICENSE) file for details.\n\n---\n\n**Note**: This SDK is designed for use with the MailTM API. Please ensure you use this SDK responsibly and adhere to MailTM's terms of service. Misuse of this SDK for illegal activities is strictly prohibited.\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A Python SDK for interacting with the Mail.tm API",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/viperadnan-git/mailtm-python-sdk"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "caaeb1b770b0010e289f8e999c820677b93a44bbbbd45568e8d761d1bde3e38e",
"md5": "65b3cbe4921680aafb4c62bbbfe13582",
"sha256": "2d482ccd0d760b2ea16ff6a0b43402822a232a439405c0977f1f4b8027fe563e"
},
"downloads": -1,
"filename": "mailtm_python-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65b3cbe4921680aafb4c62bbbfe13582",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18759,
"upload_time": "2024-09-01T09:14:15",
"upload_time_iso_8601": "2024-09-01T09:14:15.249215Z",
"url": "https://files.pythonhosted.org/packages/ca/ae/b1b770b0010e289f8e999c820677b93a44bbbbd45568e8d761d1bde3e38e/mailtm_python-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a47e34e2e3c27fd54d9aa854f7cf3d2a0633df2297c5560cb774ac5bba780036",
"md5": "b90d269dbb167bd9a0848d35ef61c4bf",
"sha256": "4224dabe3aafc163aac96c7bb6d41268b495c09becbd00060b53d56ba9ca6775"
},
"downloads": -1,
"filename": "mailtm_python-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b90d269dbb167bd9a0848d35ef61c4bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18626,
"upload_time": "2024-09-01T09:14:17",
"upload_time_iso_8601": "2024-09-01T09:14:17.082989Z",
"url": "https://files.pythonhosted.org/packages/a4/7e/34e2e3c27fd54d9aa854f7cf3d2a0633df2297c5560cb774ac5bba780036/mailtm_python-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-01 09:14:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "viperadnan-git",
"github_project": "mailtm-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mailtm-python"
}
JSON
