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

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

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

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

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

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

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",

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

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)

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

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)
@@ -53,24 +53,24 @@ def get_html_analysis(inbox_id: int, message_id: str) -> AnalysisReport:
     return messages_api.get_html_analysis(inbox_id=inbox_id, message_id=message_id)
 
 
-def get_text_body(inbox_id: int, message_id: str) -> str:
-    return messages_api.get_text_body(inbox_id=inbox_id, message_id=message_id)
+def get_text_message(inbox_id: int, message_id: str) -> str:
+    return messages_api.get_text_message(inbox_id=inbox_id, message_id=message_id)
 
 
-def get_raw_body(inbox_id: int, message_id: str) -> str:
-    return messages_api.get_raw_body(inbox_id=inbox_id, message_id=message_id)
+def get_raw_message(inbox_id: int, message_id: str) -> str:
+    return messages_api.get_raw_message(inbox_id=inbox_id, message_id=message_id)
 
 
 def get_html_source(inbox_id: int, message_id: str) -> str:
     return messages_api.get_html_source(inbox_id=inbox_id, message_id=message_id)
 
 
-def get_html_body(inbox_id: int, message_id: str) -> str:
-    return messages_api.get_html_body(inbox_id=inbox_id, message_id=message_id)
+def get_html_message(inbox_id: int, message_id: str) -> str:
+    return messages_api.get_html_message(inbox_id=inbox_id, message_id=message_id)
 
 
-def get_eml_body(inbox_id: int, message_id: str) -> str:
-    return messages_api.get_eml_body(inbox_id=inbox_id, message_id=message_id)
+def get_message_as_eml(inbox_id: int, message_id: str) -> str:
+    return messages_api.get_message_as_eml(inbox_id=inbox_id, message_id=message_id)
 
 
 def get_mail_headers(inbox_id: int, message_id: str) -> str:

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

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

mailtrap/api/resources/messages.py

@@ -107,13 +107,13 @@ def get_html_analysis(self, inbox_id: int, message_id: int) -> AnalysisReport:
         response = self._client.get(f"{self._api_path(inbox_id, message_id)}/analyze")
         return AnalysisReportResponse(**response).report
 
-    def get_text_body(self, inbox_id: int, message_id: int) -> str:
+    def get_text_message(self, inbox_id: int, message_id: int) -> str:
         """Get text email body, if it exists."""
         return cast(
             str, self._client.get(f"{self._api_path(inbox_id, message_id)}/body.txt")
         )
 
-    def get_raw_body(self, inbox_id: int, message_id: int) -> str:
+    def get_raw_message(self, inbox_id: int, message_id: int) -> str:
         """Get raw email body."""
         return cast(
             str, self._client.get(f"{self._api_path(inbox_id, message_id)}/body.raw")
@@ -126,13 +126,13 @@ def get_html_source(self, inbox_id: int, message_id: int) -> str:
             self._client.get(f"{self._api_path(inbox_id, message_id)}/body.htmlsource"),
         )
 
-    def get_html_body(self, inbox_id: int, message_id: int) -> str:
+    def get_html_message(self, inbox_id: int, message_id: int) -> str:
         """Get formatted HTML email body. Not applicable for plain text emails."""
         return cast(
             str, self._client.get(f"{self._api_path(inbox_id, message_id)}/body.html")
         )
 
-    def get_eml_body(self, inbox_id: int, message_id: int) -> str:
+    def get_message_as_eml(self, inbox_id: int, message_id: int) -> str:
         """Get email message in .eml format."""
         return cast(
             str, self._client.get(f"{self._api_path(inbox_id, message_id)}/body.eml")

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)

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