Fix issue #28: Add AttachmentsApi, releated models, tests, examples

Ihor Bilous · Ihor Bilous · commit bec8826b211f · 2025-09-16T15:36:10.000+03:00
diff --git a/examples/contacts/contact_fields.py b/examples/contacts/contact_fields.py
@@ -4,8 +4,8 @@
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import ContactField
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 contact_fields_api = client.contacts_api.contact_fields
diff --git a/examples/contacts/contact_imports.py b/examples/contacts/contact_imports.py
@@ -1,8 +1,8 @@
 import mailtrap as mt
 from mailtrap.models.contacts import ContactImport
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 contact_imports_api = client.contacts_api.contact_imports
diff --git a/examples/contacts/contact_lists.py b/examples/contacts/contact_lists.py
@@ -2,8 +2,8 @@
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import ContactList
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 contact_lists_api = client.contacts_api.contact_lists
diff --git a/examples/contacts/contacts.py b/examples/contacts/contacts.py
@@ -5,8 +5,8 @@
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import Contact
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 contacts_api = client.contacts_api.contacts
diff --git a/examples/email_templates/templates.py b/examples/email_templates/templates.py
@@ -4,8 +4,8 @@
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.templates import EmailTemplate
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 templates_api = client.email_templates_api.templates
diff --git a/examples/sending.py b/examples/sending.py
@@ -1,6 +1,6 @@
 import mailtrap as mt
 
-API_TOKEN = "<YOU_API_TOKEN>"
+API_TOKEN = "<YOUR_API_TOKEN>"
 INBOX_ID = "<YOUR_INBOX_ID>"
 
 
@@ -19,7 +19,7 @@
 mail_from_template = mt.MailFromTemplate(
     sender=mt.Address(email="<SENDER_EMAIL>", name="<SENDER_NAME>"),
     to=[mt.Address(email="<RECEIVER_EMAIL>")],
-    template_uuid="<YOUT_TEMPLATE_UUID>",
+    template_uuid="<YOUR_TEMPLATE_UUID>",
     template_variables={
         "company_info_name": "Test_Company_info_name",
         "name": "Test_Name",
diff --git a/examples/suppressions/suppressions.py b/examples/suppressions/suppressions.py
@@ -3,8 +3,8 @@
 import mailtrap as mt
 from mailtrap.models.suppressions import Suppression
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 suppressions_api = client.suppressions_api.suppressions
diff --git a/examples/testing/attachments.py b/examples/testing/attachments.py
@@ -0,0 +1,27 @@
+import mailtrap as mt
+from mailtrap.models.attachments import Attachment
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+INBOX_ID = "YOUR_INBOX_ID"
+MESSAGE_ID = "YOUR_MESSAGE_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+attachments_api = client.testing_api.attachments
+
+
+def list_attachments(inbox_id: int, message_id: int) -> list[Attachment]:
+    return attachments_api.get_list(inbox_id=inbox_id, message_id=message_id)
+
+
+def get_attachment(inbox_id: int, message_id: int, attachment_id: int) -> Attachment:
+    return attachments_api.get(
+        inbox_id=inbox_id,
+        message_id=message_id,
+        attachment_id=attachment_id,
+    )
+
+
+if __name__ == "__main__":
+    attachments = list_attachments(inbox_id=INBOX_ID, message_id=MESSAGE_ID)
+    print(attachments)
diff --git a/examples/testing/inboxes.py b/examples/testing/inboxes.py
@@ -3,8 +3,8 @@
 import mailtrap as mt
 from mailtrap.models.inboxes import Inbox
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 inboxes_api = client.testing_api.inboxes
diff --git a/examples/testing/messages.py b/examples/testing/messages.py
@@ -6,8 +6,8 @@
 from mailtrap.models.messages import ForwardedMessage
 from mailtrap.models.messages import SpamReport
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 INBOX_ID = "YOUR_INBOX_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
diff --git a/examples/testing/projects.py b/examples/testing/projects.py
@@ -1,8 +1,8 @@
 import mailtrap as mt
 from mailtrap.models.projects import Project
 
-API_TOKEN = "YOU_API_TOKEN"
-ACCOUNT_ID = "YOU_ACCOUNT_ID"
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
 
 client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
 projects_api = client.testing_api.projects
diff --git a/mailtrap/api/resources/attachments.py b/mailtrap/api/resources/attachments.py
@@ -0,0 +1,45 @@
+from typing import Optional
+
+from mailtrap.http import HttpClient
+from mailtrap.models.attachments import Attachment
+
+
+class AttachmentsApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    def get_list(
+        self,
+        inbox_id: int,
+        message_id: int,
+    ) -> list[Attachment]:
+        """Lists attachments with their details and download paths."""
+        response = self._client.get(self._api_path(inbox_id, message_id))
+        return [Attachment(**attachment) for attachment in response]
+
+    def get(
+        self,
+        inbox_id: int,
+        message_id: int,
+        attachment_id: int,
+    ) -> Attachment:
+        """Get message single attachment by inbox_id, message_id and attachment_id."""
+        response = self._client.get(self._api_path(inbox_id, message_id, attachment_id))
+        return Attachment(**response)
+
+    def _api_path(
+        self,
+        inbox_id: int,
+        message_id: int,
+        attachment_id: Optional[int] = None,
+    ) -> str:
+        path = (
+            f"/api/accounts/{self._account_id}"
+            f"/inboxes/{inbox_id}"
+            f"/messages/{message_id}"
+            "/attachments"
+        )
+        if attachment_id:
+            return f"{path}/{attachment_id}"
+        return path
diff --git a/mailtrap/api/testing.py b/mailtrap/api/testing.py
@@ -1,5 +1,6 @@
 from typing import Optional
 
+from mailtrap.api.resources.attachments import AttachmentsApi
 from mailtrap.api.resources.inboxes import InboxesApi
 from mailtrap.api.resources.messages import MessagesApi
 from mailtrap.api.resources.projects import ProjectsApi
@@ -25,3 +26,7 @@ def inboxes(self) -> InboxesApi:
     @property
     def messages(self) -> MessagesApi:
         return MessagesApi(account_id=self._account_id, client=self._client)
+
+    @property
+    def attachments(self) -> AttachmentsApi:
+        return AttachmentsApi(account_id=self._account_id, client=self._client)
diff --git a/mailtrap/models/attachments.py b/mailtrap/models/attachments.py
@@ -0,0 +1,22 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic.dataclasses import dataclass
+
+from mailtrap.models.mail.attachment import Disposition
+
+
+@dataclass
+class Attachment:
+    id: int
+    message_id: int
+    filename: str
+    attachment_type: Disposition
+    content_type: str
+    attachment_size: int
+    created_at: datetime
+    updated_at: datetime
+    attachment_human_size: str
+    download_path: str
+    content_id: Optional[str] = None
+    transfer_encoding: Optional[str] = None
diff --git a/tests/unit/api/testing/test_attachments.py b/tests/unit/api/testing/test_attachments.py
@@ -0,0 +1,159 @@
+from typing import Any
+
+import pytest
+import responses
+
+from mailtrap.api.resources.attachments import AttachmentsApi
+from mailtrap.config import GENERAL_HOST
+from mailtrap.exceptions import APIError
+from mailtrap.http import HttpClient
+from mailtrap.models.attachments import Attachment
+from tests import conftest
+
+ACCOUNT_ID = "321"
+INBOX_ID = 123
+MESSAGE_ID = 457
+ATTACHMENT_ID = 67
+
+BASE_ATTACHMENTS_URL = (
+    f"https://{GENERAL_HOST}/api/accounts/{ACCOUNT_ID}"
+    f"/inboxes/{INBOX_ID}"
+    f"/messages/{MESSAGE_ID}"
+    "/attachments"
+)
+
+
+@pytest.fixture
+def client() -> AttachmentsApi:
+    return AttachmentsApi(account_id=ACCOUNT_ID, client=HttpClient(GENERAL_HOST))
+
+
+@pytest.fixture
+def sample_attachment_dict() -> dict[str, Any]:
+    return {
+        "id": ATTACHMENT_ID,
+        "message_id": 457,
+        "filename": "test.csv",
+        "attachment_type": "inline",
+        "content_type": "plain/text",
+        "content_id": None,
+        "transfer_encoding": None,
+        "attachment_size": 0,
+        "created_at": "2022-06-02T19:25:54.827Z",
+        "updated_at": "2022-06-02T19:25:54.827Z",
+        "attachment_human_size": "0 Bytes",
+        "download_path": (
+            "/api/accounts/321"
+            "/inboxes/123"
+            "/messages/457"
+            f"/attachments/{ATTACHMENT_ID}/download"
+        ),
+    }
+
+
+class TestProjectsApi:
+    @pytest.mark.parametrize(
+        "status_code,response_json,expected_error_message",
+        [
+            (
+                conftest.UNAUTHORIZED_STATUS_CODE,
+                conftest.UNAUTHORIZED_RESPONSE,
+                conftest.UNAUTHORIZED_ERROR_MESSAGE,
+            ),
+            (
+                conftest.FORBIDDEN_STATUS_CODE,
+                conftest.FORBIDDEN_RESPONSE,
+                conftest.FORBIDDEN_ERROR_MESSAGE,
+            ),
+        ],
+    )
+    @responses.activate
+    def test_get_list_should_raise_api_errors(
+        self,
+        client: AttachmentsApi,
+        status_code: int,
+        response_json: dict,
+        expected_error_message: str,
+    ) -> None:
+        responses.get(
+            BASE_ATTACHMENTS_URL,
+            status=status_code,
+            json=response_json,
+        )
+
+        with pytest.raises(APIError) as exc_info:
+            client.get_list(INBOX_ID, MESSAGE_ID)
+
+        assert expected_error_message in str(exc_info.value)
+
+    @responses.activate
+    def test_get_list_should_return_attachments_list(
+        self, client: AttachmentsApi, sample_attachment_dict: dict
+    ) -> None:
+        responses.get(
+            BASE_ATTACHMENTS_URL,
+            json=[sample_attachment_dict],
+            status=200,
+        )
+
+        attachments = client.get_list(INBOX_ID, MESSAGE_ID)
+
+        assert isinstance(attachments, list)
+        assert all(isinstance(a, Attachment) for a in attachments)
+        assert attachments[0].id == ATTACHMENT_ID
+
+    @pytest.mark.parametrize(
+        "status_code,response_json,expected_error_message",
+        [
+            (
+                conftest.UNAUTHORIZED_STATUS_CODE,
+                conftest.UNAUTHORIZED_RESPONSE,
+                conftest.UNAUTHORIZED_ERROR_MESSAGE,
+            ),
+            (
+                conftest.FORBIDDEN_STATUS_CODE,
+                conftest.FORBIDDEN_RESPONSE,
+                conftest.FORBIDDEN_ERROR_MESSAGE,
+            ),
+            (
+                conftest.NOT_FOUND_STATUS_CODE,
+                conftest.NOT_FOUND_RESPONSE,
+                conftest.NOT_FOUND_ERROR_MESSAGE,
+            ),
+        ],
+    )
+    @responses.activate
+    def test_get_should_raise_api_errors(
+        self,
+        client: AttachmentsApi,
+        status_code: int,
+        response_json: dict,
+        expected_error_message: str,
+    ) -> None:
+        url = f"{BASE_ATTACHMENTS_URL}/{ATTACHMENT_ID}"
+        responses.get(
+            url,
+            status=status_code,
+            json=response_json,
+        )
+
+        with pytest.raises(APIError) as exc_info:
+            client.get(INBOX_ID, MESSAGE_ID, ATTACHMENT_ID)
+
+        assert expected_error_message in str(exc_info.value)
+
+    @responses.activate
+    def test_get_should_return_single_attachment(
+        self, client: AttachmentsApi, sample_attachment_dict: dict
+    ) -> None:
+        url = f"{BASE_ATTACHMENTS_URL}/{ATTACHMENT_ID}"
+        responses.get(
+            url,
+            json=sample_attachment_dict,
+            status=200,
+        )
+
+        attachment = client.get(INBOX_ID, MESSAGE_ID, ATTACHMENT_ID)
+
+        assert isinstance(attachment, Attachment)
+        assert attachment.id == ATTACHMENT_ID
