Add Inbound Email API support

README.md

@@ -244,6 +244,12 @@ The same situation applies to both `client.batch_send()` and `client.sending_api
 ### Sending Domains API:
 - Sending Domains – [`sending_domains/sending_domains.py`](examples/sending_domains/sending_domains.py)
 
+### Inbound Email API:
+- Folders management – [`inbound/folders.py`](examples/inbound/folders.py)
+- Inboxes management – [`inbound/inboxes.py`](examples/inbound/inboxes.py)
+- Messages (list/get/delete + reply/reply_all/forward) – [`inbound/messages.py`](examples/inbound/messages.py)
+- Threads (list/get/delete) – [`inbound/threads.py`](examples/inbound/threads.py)
+
 ### Webhooks API:
 - Webhooks management – [`webhooks/webhooks.py`](examples/webhooks/webhooks.py)
 - Verifying webhook signatures – [`webhooks/verify_signature.py`](examples/webhooks/verify_signature.py)

examples/contacts/contact_events.py

@@ -1,10 +1,12 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.contacts import ContactEvent
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 contact_events_api = client.contacts_api.contact_events
 
 

examples/contacts/contact_exports.py

@@ -1,10 +1,12 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.contacts import ContactExportDetail
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 contact_exports_api = client.contacts_api.contact_exports
 
 

examples/contacts/contact_fields.py

@@ -1,13 +1,14 @@
+import os
 from typing import Optional
 
 import mailtrap as mt
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import ContactField
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 contact_fields_api = client.contacts_api.contact_fields
 
 

examples/contacts/contact_imports.py

@@ -1,10 +1,12 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.contacts import ContactImport
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 contact_imports_api = client.contacts_api.contact_imports
 
 

examples/contacts/contact_lists.py

@@ -1,11 +1,13 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import ContactList
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 contact_lists_api = client.contacts_api.contact_lists
 
 

examples/contacts/contacts.py

@@ -1,14 +1,15 @@
+import os
 from typing import Optional
 from typing import Union
 
 import mailtrap as mt
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import Contact
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 contacts_api = client.contacts_api.contacts
 
 

examples/email_logs/email_logs.py

@@ -1,3 +1,5 @@
+import os
+
 """Example: List email logs and get a single message by ID."""
 
 from datetime import datetime
@@ -10,10 +12,10 @@
 from mailtrap.models.email_logs import filter_string_equal
 from mailtrap.models.email_logs import filter_string_not_empty
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 email_logs_api = client.email_logs_api.email_logs
 
 

examples/email_templates/templates.py

@@ -1,13 +1,14 @@
+import os
 from typing import Optional
 
 import mailtrap as mt
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.templates import EmailTemplate
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_KEY, account_id=ACCOUNT_ID)
 templates_api = client.email_templates_api.templates
 
 

examples/general/account_accesses.py

@@ -1,11 +1,13 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.accounts import AccountAccess
 from mailtrap.models.common import DeletedObject
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN)
+client = mt.MailtrapClient(token=API_KEY)
 account_accesses_api = client.general_api.account_accesses
 
 

examples/general/accounts.py

@@ -1,9 +1,11 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.accounts import Account
 
-API_TOKEN = "YOUR_API_TOKEN"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
 
-client = mt.MailtrapClient(token=API_TOKEN)
+client = mt.MailtrapClient(token=API_KEY)
 accounts_api = client.general_api.accounts
 
 

examples/general/api_tokens.py

@@ -1,12 +1,14 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.api_tokens import ApiToken
 from mailtrap.models.api_tokens import ApiTokenWithToken
 from mailtrap.models.common import DeletedObject
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN)
+client = mt.MailtrapClient(token=API_KEY)
 api_tokens_api = client.general_api.api_tokens
 
 

examples/general/billing.py

@@ -1,10 +1,12 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.billing import BillingCycleUsage
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN)
+client = mt.MailtrapClient(token=API_KEY)
 billing_api = client.general_api.billing
 
 

examples/general/permissions.py

@@ -1,11 +1,13 @@
+import os
+
 import mailtrap as mt
 from mailtrap.models.permissions import PermissionResource
 from mailtrap.models.permissions import UpdatePermissionsResponse
 
-API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+ACCOUNT_ID = os.environ["MAILTRAP_ACCOUNT_ID"]
 
-client = mt.MailtrapClient(token=API_TOKEN)
+client = mt.MailtrapClient(token=API_KEY)
 permissions_api = client.general_api.permissions
 
 

examples/inbound/folders.py

@@ -0,0 +1,40 @@
+import os
+
+import mailtrap as mt
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.inbound import InboundFolder
+
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+
+client = mt.MailtrapClient(token=API_KEY)
+folders_api = client.inbound_api.folders
+
+
+def list_folders() -> list[InboundFolder]:
+    return folders_api.get_list()
+
+
+def get_folder(folder_id: int) -> InboundFolder:
+    return folders_api.get_by_id(folder_id)
+
+
+def create_folder(name: str) -> InboundFolder:
+    return folders_api.create(mt.CreateInboundFolderParams(name=name))
+
+
+def update_folder(folder_id: int, name: str) -> InboundFolder:
+    return folders_api.update(folder_id, mt.UpdateInboundFolderParams(name=name))
+
+
+def delete_folder(folder_id: int) -> DeletedObject:
+    return folders_api.delete(folder_id)
+
+
+if __name__ == "__main__":
+    folder = create_folder("Support")
+    print(folder)
+
+    print(list_folders())
+    print(get_folder(folder.id))
+    print(update_folder(folder.id, "Support (renamed)"))
+    print(delete_folder(folder.id))

examples/inbound/inboxes.py

@@ -0,0 +1,42 @@
+import os
+
+import mailtrap as mt
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.inbound import InboundInbox
+
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+FOLDER_ID = int(os.environ["MAILTRAP_INBOUND_FOLDER_ID"])
+
+client = mt.MailtrapClient(token=API_KEY)
+inboxes_api = client.inbound_api.inboxes
+
+
+def list_inboxes(folder_id: int) -> list[InboundInbox]:
+    return inboxes_api.get_list(folder_id)
+
+
+def get_inbox(folder_id: int, inbox_id: int) -> InboundInbox:
+    return inboxes_api.get_by_id(folder_id, inbox_id)
+
+
+def create_inbox(folder_id: int, name: str) -> InboundInbox:
+    # Omit domain_id for a Mailtrap-hosted inbox; pass it for a custom-domain inbox.
+    return inboxes_api.create(folder_id, mt.CreateInboundInboxParams(name=name))
+
+
+def update_inbox(folder_id: int, inbox_id: int, name: str) -> InboundInbox:
+    return inboxes_api.update(folder_id, inbox_id, mt.UpdateInboundInboxParams(name=name))
+
+
+def delete_inbox(folder_id: int, inbox_id: int) -> DeletedObject:
+    return inboxes_api.delete(folder_id, inbox_id)
+
+
+if __name__ == "__main__":
+    inbox = create_inbox(FOLDER_ID, "Tickets")
+    print(inbox)
+
+    print(list_inboxes(FOLDER_ID))
+    print(get_inbox(FOLDER_ID, inbox.id))
+    print(update_inbox(FOLDER_ID, inbox.id, "Tickets (renamed)"))
+    print(delete_inbox(FOLDER_ID, inbox.id))

examples/inbound/messages.py

@@ -0,0 +1,55 @@
+import os
+
+import mailtrap as mt
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.inbound import InboundMessageDetails
+from mailtrap.models.inbound import InboundMessagesListResponse
+from mailtrap.models.inbound import InboundSendResult
+from mailtrap.models.mail.address import Address
+
+API_KEY = os.environ["MAILTRAP_API_KEY"]
+INBOX_ID = int(os.environ["MAILTRAP_INBOUND_INBOX_ID"])
+
+client = mt.MailtrapClient(token=API_KEY)
+messages_api = client.inbound_api.messages
+
+
+def list_messages(inbox_id: int) -> InboundMessagesListResponse:
+    # Pass last_id from the previous page to paginate.
+    return messages_api.get_list(inbox_id)
+
+
+def get_message(inbox_id: int, message_id: str) -> InboundMessageDetails:
+    return messages_api.get_by_id(inbox_id, message_id)
+
+
+def delete_message(inbox_id: int, message_id: str) -> DeletedObject:
+    return messages_api.delete(inbox_id, message_id)
+
+
+def reply(inbox_id: int, message_id: str, text: str) -> InboundSendResult:
+    params = mt.ReplyInboundMessageParams(text=text)
+    return messages_api.reply(inbox_id, message_id, params)
+
+
+def reply_all(inbox_id: int, message_id: str, text: str) -> InboundSendResult:
+    params = mt.ReplyInboundMessageParams(text=text)
+    return messages_api.reply_all(inbox_id, message_id, params)
+
+
+def forward(inbox_id: int, message_id: str, to: str) -> InboundSendResult:
+    params = mt.ForwardInboundMessageParams(to=[Address(email=to)])
+    return messages_api.forward(inbox_id, message_id, params)
+
+
+if __name__ == "__main__":
+    page = list_messages(INBOX_ID)
+    print(f"{len(page.data)} of {page.total_count} messages")
+
+    if page.data:
+        message_id = page.data[0].id
+        print(get_message(INBOX_ID, message_id))
+        print(reply(INBOX_ID, message_id, "Thanks for reaching out!"))
+        print(reply_all(INBOX_ID, message_id, "Looping everyone in."))
+        print(forward(INBOX_ID, message_id, "colleague@example.com"))
+        print(delete_message(INBOX_ID, message_id))