MT-22401: Add Email Campaigns API to Python SDK

Implement the token-scoped /api/email_campaigns resource (list, create,
get, update, delete, stats) with pydantic models, params DTOs, client
wiring, example, and unit tests.

- list returns {data, pagination}; create/get/update/delete return a
  bare EmailCampaign; stats returns a bare EmailCampaignStats
- delete returns HTTP 200 + the deleted entity (not 204/DeletedObject)
- request body wraps under the email_campaign key
- list name filter serializes to the search wire param
- EmailCampaignStats defined once, reused for inline stats + /stats

Author: Rabsztok

README.md

@@ -244,6 +244,9 @@ 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)
 
+### Email Campaigns API:
+- Email Campaigns (list, create, get, update, delete, stats) – [`email_campaigns/email_campaigns.py`](examples/email_campaigns/email_campaigns.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/email_campaigns/email_campaigns.py

@@ -0,0 +1,87 @@
+import mailtrap as mt
+from mailtrap.models.email_campaigns import EmailCampaign
+from mailtrap.models.email_campaigns import EmailCampaignListResponse
+from mailtrap.models.email_campaigns import EmailCampaignStats
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+email_campaigns_api = client.email_campaigns_api.email_campaigns
+
+
+def list_email_campaigns() -> EmailCampaignListResponse:
+    # `search` filters by name (case-insensitive partial match); `token` is the
+    # page number (page-token pagination); `per_page` caps at 100 (default 50).
+    return email_campaigns_api.get_list(per_page=50, search="Spring", token=1)
+
+
+def get_email_campaign(email_campaign_id: int) -> EmailCampaign:
+    return email_campaigns_api.get_by_id(email_campaign_id=email_campaign_id)
+
+
+def create_email_campaign() -> EmailCampaign:
+    # A campaign is created in the `draft` state and must reference a verified
+    # sending domain via `mailsend_domain_id`.
+    return email_campaigns_api.create(
+        mt.CreateEmailCampaignParams(
+            name="Spring Sale",
+            mailsend_domain_id=123,
+            from_display_name="Acme Marketing",
+            from_local_part="news",
+            reply_to=mt.ReplyTo(
+                display_name="Acme Support",
+                local_part="support",
+                domain="acme.com",
+            ),
+            template_attributes=mt.CampaignTemplate(subject="Spring is here — 30% off"),
+        )
+    )
+
+
+def update_email_campaign(email_campaign_id: int, template_id: int) -> EmailCampaign:
+    # Only supplied fields are changed. Pass the existing template `id` to
+    # update its subject in place instead of creating a new template.
+    return email_campaigns_api.update(
+        email_campaign_id=email_campaign_id,
+        campaign_params=mt.UpdateEmailCampaignParams(
+            name="Spring Sale (updated)",
+            delivery_mode="scheduled",
+            scheduled_for="2026-06-01T09:00:00.000Z",
+            delivery_options=mt.DeliveryOptions(emails_per_hour=1000),
+            template_attributes=mt.CampaignTemplate(
+                id=template_id, subject="New subject"
+            ),
+        ),
+    )
+
+
+def delete_email_campaign(email_campaign_id: int) -> EmailCampaign:
+    # The deleted campaign object is returned (HTTP 200 + body).
+    return email_campaigns_api.delete(email_campaign_id=email_campaign_id)
+
+
+def get_email_campaign_stats(email_campaign_id: int) -> EmailCampaignStats:
+    return email_campaigns_api.get_stats(email_campaign_id=email_campaign_id)
+
+
+if __name__ == "__main__":
+    listed = list_email_campaigns()
+    print(listed.data)
+    print(listed.pagination)
+
+    created = create_email_campaign()
+    print(created)
+
+    fetched = get_email_campaign(created.id)
+    print(fetched)
+
+    template_id = created.template.id if created.template else 0
+    updated = update_email_campaign(created.id, template_id)
+    print(updated)
+
+    stats = get_email_campaign_stats(created.id)
+    print(stats)
+
+    deleted = delete_email_campaign(created.id)
+    print(deleted)

mailtrap/__init__.py

@@ -17,6 +17,11 @@
 from .models.contacts import ImportContactParams
 from .models.contacts import UpdateContactFieldParams
 from .models.contacts import UpdateContactParams
+from .models.email_campaigns import CampaignTemplate
+from .models.email_campaigns import CreateEmailCampaignParams
+from .models.email_campaigns import DeliveryOptions
+from .models.email_campaigns import ReplyTo
+from .models.email_campaigns import UpdateEmailCampaignParams
 from .models.email_logs import EmailLogMessage
 from .models.email_logs import EmailLogsListFilters
 from .models.email_logs import EmailLogsListResponse

mailtrap/api/email_campaigns.py

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

mailtrap/api/resources/email_campaigns.py

@@ -0,0 +1,88 @@
+from typing import Optional
+
+from mailtrap.http import HttpClient
+from mailtrap.models.email_campaigns import CreateEmailCampaignParams
+from mailtrap.models.email_campaigns import EmailCampaign
+from mailtrap.models.email_campaigns import EmailCampaignListParams
+from mailtrap.models.email_campaigns import EmailCampaignListResponse
+from mailtrap.models.email_campaigns import EmailCampaignStats
+from mailtrap.models.email_campaigns import UpdateEmailCampaignParams
+
+
+class EmailCampaignsApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    def get_list(
+        self,
+        per_page: Optional[int] = None,
+        search: Optional[str] = None,
+        token: Optional[int] = None,
+    ) -> EmailCampaignListResponse:
+        """
+        List email campaigns for the account, newest first. ``search`` filters
+        by name (case-insensitive partial match), ``per_page`` sets the page
+        size (max 100, default 50), and ``token`` is the page number to
+        retrieve (default 1).
+        """
+        params = EmailCampaignListParams(
+            per_page=per_page, search=search, token=token
+        ).api_query_params
+        response = self._client.get(self._api_path(), params=params or None)
+        return EmailCampaignListResponse(**response)
+
+    def get_by_id(self, email_campaign_id: int) -> EmailCampaign:
+        """
+        Get a single email campaign by id.
+        """
+        response = self._client.get(self._api_path(email_campaign_id))
+        return EmailCampaign(**response)
+
+    def create(self, campaign_params: CreateEmailCampaignParams) -> EmailCampaign:
+        """
+        Create a new email campaign in the ``draft`` state. The campaign must
+        reference an existing sending domain via ``mailsend_domain_id``.
+        """
+        response = self._client.post(
+            self._api_path(), json={"email_campaign": campaign_params.api_data}
+        )
+        return EmailCampaign(**response)
+
+    def update(
+        self, email_campaign_id: int, campaign_params: UpdateEmailCampaignParams
+    ) -> EmailCampaign:
+        """
+        Update an existing email campaign. The campaign must not be in a
+        sending state. Only the fields supplied in ``campaign_params`` are sent
+        to the API.
+        """
+        response = self._client.patch(
+            self._api_path(email_campaign_id),
+            json={"email_campaign": campaign_params.api_data},
+        )
+        return EmailCampaign(**response)
+
+    def delete(self, email_campaign_id: int) -> EmailCampaign:
+        """
+        Delete an email campaign. The campaign must not be in a sending state.
+        The deleted campaign object is returned (HTTP 200 + body, not 204).
+        """
+        response = self._client.delete(self._api_path(email_campaign_id))
+        return EmailCampaign(**response)
+
+    def get_stats(self, email_campaign_id: int) -> EmailCampaignStats:
+        """
+        Get aggregated performance statistics for a single campaign. If the
+        campaign has never been started, all counts and rates are ``0``.
+        """
+        response = self._client.get(f"{self._api_path(email_campaign_id)}/stats")
+        return EmailCampaignStats(**response)
+
+    def _api_path(self, email_campaign_id: Optional[int] = None) -> str:
+        # The Email Campaigns endpoint is token-scoped, NOT account-scoped:
+        # the account is resolved from the API token server-side.
+        path = "/api/email_campaigns"
+        if email_campaign_id is not None:
+            return f"{path}/{email_campaign_id}"
+        return path

mailtrap/client.py

@@ -7,6 +7,7 @@
 from pydantic import TypeAdapter
 
 from mailtrap.api.contacts import ContactsBaseApi
+from mailtrap.api.email_campaigns import EmailCampaignsBaseApi
 from mailtrap.api.email_logs import EmailLogsBaseApi
 from mailtrap.api.general import GeneralApi
 from mailtrap.api.organizations import OrganizationsBaseApi
@@ -117,6 +118,14 @@ def sending_domains_api(self) -> SendingDomainsBaseApi:
             client=HttpClient(host=GENERAL_HOST, headers=self.headers),
         )
 
+    @property
+    def email_campaigns_api(self) -> EmailCampaignsBaseApi:
+        self._validate_account_id("Email Campaigns API")
+        return EmailCampaignsBaseApi(
+            account_id=cast(str, self.account_id),
+            client=HttpClient(host=GENERAL_HOST, headers=self.headers),
+        )
+
     @property
     def email_logs_api(self) -> EmailLogsBaseApi:
         self._validate_account_id("Email Logs API")

mailtrap/models/email_campaigns.py

@@ -0,0 +1,161 @@
+"""Models for the Email Campaigns API (campaigns + stats)."""
+
+from typing import Optional
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from mailtrap.models.common import RequestParams
+
+
+@dataclass
+class ReplyTo:
+    """Reply-To address parts."""
+
+    display_name: Optional[str] = None
+    local_part: Optional[str] = None
+    domain: Optional[str] = None
+
+
+@dataclass
+class EmailCampaignStats:
+    """
+    Aggregated campaign performance metrics. All counts and rates are ``0``
+    when the campaign has not been started. The same shape is returned both
+    inline on an ``EmailCampaign`` (its ``stats`` member) and as the standalone
+    ``/stats`` response.
+    """
+
+    delivery_count: Optional[int] = None
+    open_count: Optional[int] = None
+    click_count: Optional[int] = None
+    bounce_count: Optional[int] = None
+    unsubscription_count: Optional[int] = None
+    sent_count: Optional[int] = None
+    spam_count: Optional[int] = None
+    message_count: Optional[int] = None
+    reject_count: Optional[int] = None
+    delivery_rate: Optional[float] = None
+    open_rate: Optional[float] = None
+    click_rate: Optional[float] = None
+    bounce_rate: Optional[float] = None
+    spam_rate: Optional[float] = None
+    unsubscription_rate: Optional[float] = None
+
+
+@dataclass
+class CurrentStateMetadata:
+    """Metadata about the most recent campaign state transition."""
+
+    reason: Optional[str] = None
+    error: Optional[str] = None
+    scheduled_at: Optional[str] = None
+    errors: list[str] = Field(default_factory=list)
+
+
+@dataclass
+class DeliveryOptions:
+    """Delivery throttling options."""
+
+    emails_per_hour: Optional[int] = None
+
+
+@dataclass
+class CampaignTemplate:
+    """The campaign template reference."""
+
+    id: Optional[int] = None
+    subject: Optional[str] = None
+
+
+@dataclass
+class EmailCampaign:
+    """A single email campaign."""
+
+    id: int
+    type: Optional[str] = None
+    mailsend_domain_id: Optional[int] = None
+    mailsend_domain_name: Optional[str] = None
+    name: Optional[str] = None
+    from_local_part: Optional[str] = None
+    from_display_name: Optional[str] = None
+    reply_to: Optional[ReplyTo] = None
+    current_state: Optional[str] = None
+    current_state_metadata: Optional[CurrentStateMetadata] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    last_started_at: Optional[str] = None
+    last_started_at_date: Optional[str] = None
+    recipient_total_count: Optional[int] = None
+    delivery_mode: Optional[str] = None
+    delivery_options: Optional[DeliveryOptions] = None
+    scheduled_for: Optional[str] = None
+    # Omitted from list items.
+    audience_defined: Optional[bool] = None
+    # Present only when the campaign carries stats.
+    stats: Optional[EmailCampaignStats] = None
+    template: Optional[CampaignTemplate] = None
+
+
+@dataclass
+class Pagination:
+    """Page-token pagination metadata."""
+
+    token: Optional[int] = None
+    prev_token: Optional[int] = None
+    next_token: Optional[int] = None
+    first_url: Optional[str] = None
+    prev_url: Optional[str] = None
+    current_url: Optional[str] = None
+    next_url: Optional[str] = None
+
+
+@dataclass
+class EmailCampaignListResponse:
+    """Paginated response from listing email campaigns."""
+
+    data: list[EmailCampaign] = Field(default_factory=list)
+    pagination: Optional[Pagination] = None
+
+
+@dataclass
+class EmailCampaignListParams(RequestParams):
+    """
+    Query params for listing email campaigns. ``search`` filters by name
+    (case-insensitive partial match) and serializes to the ``search`` wire
+    parameter.
+    """
+
+    per_page: Optional[int] = None
+    search: Optional[str] = None
+    token: Optional[int] = None
+
+
+@dataclass
+class CreateEmailCampaignParams(RequestParams):
+    """Attributes for creating an email campaign (wrapped under ``email_campaign``)."""
+
+    name: str
+    mailsend_domain_id: int
+    from_display_name: Optional[str] = None
+    from_local_part: Optional[str] = None
+    reply_to: Optional[ReplyTo] = None
+    template_attributes: Optional[CampaignTemplate] = None
+
+
+@dataclass
+class UpdateEmailCampaignParams(RequestParams):
+    """
+    Attributes for updating an email campaign (wrapped under ``email_campaign``).
+    All fields are optional; only provided fields are changed.
+    """
+
+    name: Optional[str] = None
+    mailsend_domain_id: Optional[int] = None
+    from_display_name: Optional[str] = None
+    from_local_part: Optional[str] = None
+    delivery_mode: Optional[str] = None
+    scheduled_for: Optional[str] = None
+    delivery_options: Optional[DeliveryOptions] = None
+    reply_to: Optional[ReplyTo] = None
+    template_attributes: Optional[CampaignTemplate] = None