Fix issue #54: Add SendingDomainsApi, related models, tests, examples

Author: Ihor Bilous

README.md

@@ -241,6 +241,9 @@ The same situation applies to both `client.batch_send()` and `client.sending_api
 ### Email Templates API:
 - Templates management – [`email_templates/templates.py`](examples/email_templates/templates.py)
 
+### Sending Domains API:
+- Sending Domains – [`sending_domains/sending_domains.py`](examples/sending_domains/sending_domains.py)
+
 ### Suppressions API:
 - Suppressions (find & delete) – [`suppressions/suppressions.py`](examples/suppressions/suppressions.py)
 

examples/sending_domains/sending_domains.py

@@ -0,0 +1,49 @@
+import mailtrap as mt
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.sending_domains import SendingDomain
+from mailtrap.models.sending_domains import SendSetupInstructionsResponse
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+sending_domains_api = client.sending_domains_api.sending_domains
+
+
+def list_sending_domains() -> list[SendingDomain]:
+    return sending_domains_api.get_list()
+
+
+def get_sending_domain(domain_id: int) -> SendingDomain:
+    return sending_domains_api.get_by_id(domain_id)
+
+
+def create_sending_domain(domain_name: str) -> SendingDomain:
+    params = mt.CreateSendingDomainParams(domain_name=domain_name)
+    return sending_domains_api.create(params)
+
+
+def delete_sending_domain(domain_id: int) -> DeletedObject:
+    return sending_domains_api.delete(domain_id)
+
+
+def send_setup_instructions(domain_id: int, email: str) -> SendSetupInstructionsResponse:
+    params = mt.SendSetupInstructionsParams(email=email)
+    return sending_domains_api.send_setup_instructions(domain_id, params)
+
+
+if __name__ == "__main__":
+    new_domain = create_sending_domain("example.com")
+    print(new_domain)
+
+    domains = list_sending_domains()
+    print(domains)
+
+    domain = get_sending_domain(new_domain.id)
+    print(domain)
+
+    response = send_setup_instructions(new_domain.id, "example@mail.com")
+    print(response)
+
+    deleted_domain = delete_sending_domain(new_domain.id)
+    print(deleted_domain)

mailtrap/__init__.py

@@ -30,5 +30,7 @@
 from .models.messages import UpdateEmailMessageParams
 from .models.permissions import PermissionResourceParams
 from .models.projects import ProjectParams
+from .models.sending_domains import CreateSendingDomainParams
+from .models.sending_domains import SendSetupInstructionsParams
 from .models.templates import CreateEmailTemplateParams
 from .models.templates import UpdateEmailTemplateParams

mailtrap/api/resources/sending_domains.py

@@ -0,0 +1,69 @@
+from typing import Optional
+
+from mailtrap.http import HttpClient
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.sending_domains import CreateSendingDomainParams
+from mailtrap.models.sending_domains import SendingDomain
+from mailtrap.models.sending_domains import SendSetupInstructionsParams
+from mailtrap.models.sending_domains import SendSetupInstructionsResponse
+
+
+class SendingDomainsApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    def get_list(self) -> list[SendingDomain]:
+        """
+        Get sending domains and their statuses.
+        """
+        response = self._client.get(self._api_path())
+        domains = response.get("data", [])
+        return [SendingDomain(**domain) for domain in domains]
+
+    def get_by_id(self, sending_domain_id: int) -> SendingDomain:
+        """
+        Get domain data and its status.
+        """
+        response = self._client.get(self._api_path(sending_domain_id))
+        return SendingDomain(**response)
+
+    def create(self, domain_params: CreateSendingDomainParams) -> SendingDomain:
+        """
+        Create a sending domain. To later check the status of the newly created domain,
+        review the compliance_status and dns_verified fields in the response
+        of the Get domain by ID or Get sending domains endpoints.
+        """
+        response = self._client.post(
+            self._api_path(), json={"sending_domain": domain_params.api_data}
+        )
+        return SendingDomain(**response)
+
+    def delete(self, sending_domain_id: int) -> DeletedObject:
+        """
+        Delete a sending domain.
+        """
+        self._client.delete(self._api_path(sending_domain_id))
+        return DeletedObject(id=sending_domain_id)
+
+    def send_setup_instructions(
+        self,
+        sending_domain_id: int,
+        instructions_params: SendSetupInstructionsParams,
+    ) -> SendSetupInstructionsResponse:
+        """
+        Send sending domain setup instructions.
+        """
+        self._client.post(
+            f"{self._api_path(sending_domain_id)}/send_setup_instructions",
+            json=instructions_params.api_data,
+        )
+        return SendSetupInstructionsResponse(
+            message="Instructions email has been sent successfully"
+        )
+
+    def _api_path(self, sending_domain_id: Optional[int] = None) -> str:
+        path = f"/api/accounts/{self._account_id}/sending_domains"
+        if sending_domain_id is not None:
+            path = f"{path}/{sending_domain_id}"
+        return path

mailtrap/api/sending_domains.py

@@ -0,0 +1,12 @@
+from mailtrap.api.resources.sending_domains import SendingDomainsApi
+from mailtrap.http import HttpClient
+
+
+class SendingDomainsBaseApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    @property
+    def sending_domains(self) -> SendingDomainsApi:
+        return SendingDomainsApi(account_id=self._account_id, client=self._client)

mailtrap/client.py

@@ -8,6 +8,7 @@
 from mailtrap.api.contacts import ContactsBaseApi
 from mailtrap.api.general import GeneralApi
 from mailtrap.api.sending import SendingApi
+from mailtrap.api.sending_domains import SendingDomainsBaseApi
 from mailtrap.api.suppressions import SuppressionsBaseApi
 from mailtrap.api.templates import EmailTemplatesApi
 from mailtrap.api.testing import TestingApi
@@ -93,6 +94,14 @@ def suppressions_api(self) -> SuppressionsBaseApi:
             client=HttpClient(host=GENERAL_HOST, headers=self.headers),
         )
 
+    @property
+    def sending_domains_api(self) -> SendingDomainsBaseApi:
+        self._validate_account_id()
+        return SendingDomainsBaseApi(
+            account_id=cast(str, self.account_id),
+            client=HttpClient(host=GENERAL_HOST, headers=self.headers),
+        )
+
     @property
     def sending_api(self) -> SendingApi:
         http_client = HttpClient(host=self._sending_api_host, headers=self.headers)

mailtrap/models/sending_domains.py

@@ -0,0 +1,57 @@
+from typing import Optional
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from mailtrap.models.common import RequestParams
+
+
+@dataclass
+class SendingDomainPermissions:
+    can_read: bool
+    can_update: bool
+    can_destroy: bool
+
+
+@dataclass
+class DnsRecord:
+    key: str
+    domain: str
+    type: str
+    value: str
+    status: str
+    name: str
+
+
+@dataclass
+class SendingDomain:
+    id: int
+    domain_name: str
+    demo: bool
+    compliance_status: str
+    dns_verified: bool
+    open_tracking_enabled: bool
+    click_tracking_enabled: bool
+    auto_unsubscribe_link_enabled: bool
+    custom_domain_tracking_enabled: bool
+    health_alerts_enabled: bool
+    critical_alerts_enabled: bool
+    permissions: SendingDomainPermissions
+    alert_recipient_email: Optional[str] = None
+    dns_verified_at: Optional[str] = None
+    dns_records: list[DnsRecord] = Field(default_factory=list)
+
+
+@dataclass
+class CreateSendingDomainParams(RequestParams):
+    domain_name: str
+
+
+@dataclass
+class SendSetupInstructionsParams(RequestParams):
+    email: str
+
+
+@dataclass
+class SendSetupInstructionsResponse:
+    message: str