Fix issue #27: Add InboxesApi, related models, examples. Improve ProjectsApi with parameters classes, add docstring to all resources methods.

Author: Ihor Bilous

examples/testing/inboxes.py

@@ -0,0 +1,63 @@
+from typing import Optional
+
+import mailtrap as mt
+from mailtrap.models.inboxes import Inbox
+
+API_TOKEN = "YOU_API_TOKEN"
+ACCOUNT_ID = "YOU_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+inboxes_api = client.testing_api.inboxes
+
+
+def list_inboxes() -> list[Inbox]:
+    return inboxes_api.get_list()
+
+
+def create_inbox(project_id: int, inbox_name: str) -> Inbox:
+    return inboxes_api.create(
+        project_id=project_id, inbox_params=mt.CreateInboxParams(name=inbox_name)
+    )
+
+
+def get_inbox_by_id(inbox_id: int) -> Inbox:
+    return inboxes_api.get_by_id(inbox_id)
+
+
+def update_inbox(
+    inbox_id: int,
+    new_name: Optional[str] = None,
+    new_email_username: Optional[str] = None,
+) -> Inbox:
+    return inboxes_api.update(
+        inbox_id, mt.UpdateInboxParams(name=new_name, email_username=new_email_username)
+    )
+
+
+def clean_inbox(inbox_id: int) -> Inbox:
+    return inboxes_api.clean(inbox_id)
+
+
+def mark_inbox_as_read(inbox_id: int) -> Inbox:
+    return inboxes_api.mark_as_read(inbox_id)
+
+
+def reset_inbox_credentials(inbox_id: int) -> Inbox:
+    return inboxes_api.reset_credentials(inbox_id)
+
+
+def enable_inbox_email_address(inbox_id: int) -> Inbox:
+    return inboxes_api.enable_email_address(inbox_id)
+
+
+def reset_inbox_email_username(inbox_id: int) -> Inbox:
+    return inboxes_api.reset_email_username(inbox_id)
+
+
+def delete_inbox(inbox_id: int):
+    return inboxes_api.delete(inbox_id)
+
+
+if __name__ == "__main__":
+    inboxes = list_inboxes()
+    print(inboxes)

examples/testing/projects.py

@@ -1,26 +1,30 @@
-from mailtrap import MailtrapClient
+import mailtrap as mt
 from mailtrap.models.projects import Project
 
 API_TOKEN = "YOU_API_TOKEN"
 ACCOUNT_ID = "YOU_ACCOUNT_ID"
 
-client = MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 projects_api = client.testing_api.projects
 
 
 def list_projects() -> list[Project]:
     return projects_api.get_list()
 
 
-def create_project(project_name: str) -> Project:
-    return projects_api.create(project_name=project_name)
+def get_project(project_id: int) -> Project:
+    return projects_api.get_by_id(project_id)
 
 
-def update_project(project_id: str, new_name: str) -> Project:
-    return projects_api.update(project_id, new_name)
+def create_project(name: str) -> Project:
+    return projects_api.create(project_params=mt.ProjectParams(name=name))
 
 
-def delete_project(project_id: str):
+def update_project(project_id: int, new_name: str) -> Project:
+    return projects_api.update(project_id, mt.ProjectParams(name=new_name))
+
+
+def delete_project(project_id: int):
     return projects_api.delete(project_id)
 
 

mailtrap/__init__.py

@@ -10,11 +10,14 @@
 from .models.contacts import ImportContactParams
 from .models.contacts import UpdateContactFieldParams
 from .models.contacts import UpdateContactParams
+from .models.inboxes import CreateInboxParams
+from .models.inboxes import UpdateInboxParams
 from .models.mail import Address
 from .models.mail import Attachment
 from .models.mail import BaseMail
 from .models.mail import Disposition
 from .models.mail import Mail
 from .models.mail import MailFromTemplate
+from .models.projects import ProjectParams
 from .models.templates import CreateEmailTemplateParams
 from .models.templates import UpdateEmailTemplateParams

mailtrap/api/resources/contact_fields.py

@@ -13,16 +13,19 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def get_list(self) -> list[ContactField]:
+        """Get all Contact Fields existing in your account."""
         response = self._client.get(self._api_path())
         return [ContactField(**field) for field in response]
 
     def get_by_id(self, field_id: int) -> ContactField:
+        """Get a contact Field by ID."""
         response = self._client.get(
             self._api_path(field_id),
         )
         return ContactField(**response)
 
     def create(self, field_params: CreateContactFieldParams) -> ContactField:
+        """Create new Contact Fields. Please note, you can have up to 40 fields."""
         response = self._client.post(
             self._api_path(),
             json=field_params.api_data,
@@ -32,13 +35,22 @@ def create(self, field_params: CreateContactFieldParams) -> ContactField:
     def update(
         self, field_id: int, field_params: UpdateContactFieldParams
     ) -> ContactField:
+        """
+        Update existing Contact Field. Please note,
+        you cannot change data_type of the field.
+        """
         response = self._client.patch(
             self._api_path(field_id),
             json=field_params.api_data,
         )
         return ContactField(**response)
 
     def delete(self, field_id: int) -> DeletedObject:
+        """
+        Delete existing Contact Field Please, note, you cannot delete a Contact Field
+        which is used in Automations, Email Campaigns (started or scheduled), and in
+        conditions of Contact Segments (you'll see the corresponding error)
+        """
         self._client.delete(self._api_path(field_id))
         return DeletedObject(field_id)
 

mailtrap/api/resources/contact_imports.py

@@ -11,13 +11,20 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def import_contacts(self, contacts: list[ImportContactParams]) -> ContactImport:
+        """
+        Import contacts in bulk with support for custom fields and list management.
+        Existing contacts with matching email addresses will be updated automatically.
+        You can import up to 50,000 contacts per request. The import process runs
+        asynchronously - use the returned import ID to check the status and results.
+        """
         response = self._client.post(
             self._api_path(),
             json={"contacts": [contact.api_data for contact in contacts]},
         )
         return ContactImport(**response)
 
     def get_by_id(self, import_id: int) -> ContactImport:
+        """Get Contact Import by ID."""
         response = self._client.get(self._api_path(import_id))
         return ContactImport(**response)
 

mailtrap/api/resources/contact_lists.py

@@ -12,28 +12,33 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def get_list(self) -> list[ContactList]:
+        """Get all contact lists existing in your account."""
         response = self._client.get(self._api_path())
         return [ContactList(**field) for field in response]
 
     def get_by_id(self, list_id: int) -> ContactList:
+        """Get a contact list by ID."""
         response = self._client.get(self._api_path(list_id))
         return ContactList(**response)
 
     def create(self, list_params: ContactListParams) -> ContactList:
+        """Create new Contact Lists."""
         response = self._client.post(
             self._api_path(),
             json=list_params.api_data,
         )
         return ContactList(**response)
 
     def update(self, list_id: int, list_params: ContactListParams) -> ContactList:
+        """Update existing Contact List."""
         response = self._client.patch(
             self._api_path(list_id),
             json=list_params.api_data,
         )
         return ContactList(**response)
 
     def delete(self, list_id: int) -> DeletedObject:
+        """Delete existing Contact List."""
         self._client.delete(self._api_path(list_id))
         return DeletedObject(list_id)
 

mailtrap/api/resources/contacts.py

@@ -15,10 +15,12 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def get_by_id(self, contact_id_or_email: str) -> Contact:
+        """Get contact using id or email (URL encoded)."""
         response = self._client.get(self._api_path(contact_id_or_email))
         return ContactResponse(**response).data
 
     def create(self, contact_params: CreateContactParams) -> Contact:
+        """Create a new contact."""
         response = self._client.post(
             self._api_path(),
             json={"contact": contact_params.api_data},
@@ -28,13 +30,15 @@ def create(self, contact_params: CreateContactParams) -> Contact:
     def update(
         self, contact_id_or_email: str, contact_params: UpdateContactParams
     ) -> Contact:
+        """Update contact using id or email (URL encoded)."""
         response = self._client.patch(
             self._api_path(contact_id_or_email),
             json={"contact": contact_params.api_data},
         )
         return ContactResponse(**response).data
 
     def delete(self, contact_id_or_email: str) -> DeletedObject:
+        """Delete contact using id or email (URL encoded)."""
         self._client.delete(self._api_path(contact_id_or_email))
         return DeletedObject(contact_id_or_email)
 

mailtrap/api/resources/inboxes.py

@@ -0,0 +1,74 @@
+from typing import Optional
+
+from mailtrap.http import HttpClient
+from mailtrap.models.inboxes import CreateInboxParams
+from mailtrap.models.inboxes import Inbox
+from mailtrap.models.inboxes import UpdateInboxParams
+
+
+class InboxesApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    def get_list(self) -> list[Inbox]:
+        """Get a list of inboxes."""
+        response = self._client.get(self._api_path())
+        return [Inbox(**inbox) for inbox in response]
+
+    def get_by_id(self, inbox_id: int) -> Inbox:
+        """Get inbox attributes by inbox id."""
+        response = self._client.get(self._api_path(inbox_id))
+        return Inbox(**response)
+
+    def create(self, project_id: int, inbox_params: CreateInboxParams) -> Inbox:
+        """Create an inbox in a project."""
+        response = self._client.post(
+            f"/api/accounts/{self._account_id}/projects/{project_id}/inboxes",
+            json={"inbox": inbox_params.api_data},
+        )
+        return Inbox(**response)
+
+    def update(self, inbox_id: int, inbox_params: UpdateInboxParams) -> Inbox:
+        """Update inbox name, inbox email username."""
+        response = self._client.patch(
+            self._api_path(inbox_id),
+            json={"inbox": inbox_params.api_data},
+        )
+        return Inbox(**response)
+
+    def delete(self, inbox_id: int) -> Inbox:
+        """Delete an inbox with all its emails."""
+        response = self._client.delete(self._api_path(inbox_id))
+        return Inbox(**response)
+
+    def clean(self, inbox_id: int) -> Inbox:
+        """Delete all messages (emails) from inbox."""
+        response = self._client.patch(f"{self._api_path(inbox_id)}/clean")
+        return Inbox(**response)
+
+    def mark_as_read(self, inbox_id: int) -> Inbox:
+        """Mark all messages in the inbox as read."""
+        response = self._client.patch(f"{self._api_path(inbox_id)}/all_read")
+        return Inbox(**response)
+
+    def reset_credentials(self, inbox_id: int) -> Inbox:
+        """Reset SMTP credentials of the inbox."""
+        response = self._client.patch(f"{self._api_path(inbox_id)}/reset_credentials")
+        return Inbox(**response)
+
+    def enable_email_address(self, inbox_id: int) -> Inbox:
+        """Turn the email address of the inbox on/off."""
+        response = self._client.patch(f"{self._api_path(inbox_id)}/toggle_email_username")
+        return Inbox(**response)
+
+    def reset_email_username(self, inbox_id: int) -> Inbox:
+        """Reset username of email address per inbox."""
+        response = self._client.patch(f"{self._api_path(inbox_id)}/reset_email_username")
+        return Inbox(**response)
+
+    def _api_path(self, inbox_id: Optional[int] = None) -> str:
+        path = f"/api/accounts/{self._account_id}/inboxes"
+        if inbox_id:
+            return f"{path}/{inbox_id}"
+        return path

mailtrap/api/resources/projects.py

@@ -3,6 +3,7 @@
 from mailtrap.http import HttpClient
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.projects import Project
+from mailtrap.models.projects import ProjectParams
 
 
 class ProjectsApi:
@@ -11,28 +12,39 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def get_list(self) -> list[Project]:
+        """List projects and their inboxes to which the API token has access."""
         response = self._client.get(self._api_path())
         return [Project(**project) for project in response]
 
     def get_by_id(self, project_id: int) -> Project:
+        """Get the project and its inboxes."""
         response = self._client.get(self._api_path(project_id))
         return Project(**response)
 
-    def create(self, project_name: str) -> Project:
+    def create(self, project_params: ProjectParams) -> Project:
+        """
+        Create a new project.
+        The project name is min 2 characters and max 100 characters long.
+        """
         response = self._client.post(
             self._api_path(),
-            json={"project": {"name": project_name}},
+            json={"project": project_params.api_data},
         )
         return Project(**response)
 
-    def update(self, project_id: int, project_name: str) -> Project:
+    def update(self, project_id: int, project_params: ProjectParams) -> Project:
+        """
+        Update project name.
+        The project name is min 2 characters and max 100 characters long.
+        """
         response = self._client.patch(
             self._api_path(project_id),
-            json={"project": {"name": project_name}},
+            json={"project": project_params.api_data},
         )
         return Project(**response)
 
     def delete(self, project_id: int) -> DeletedObject:
+        """Delete project and its inboxes."""
         response = self._client.delete(self._api_path(project_id))
         return DeletedObject(**response)