MT-22401: Add Email Campaigns API

[Rabsztok]

Draft until the server-side Email Campaigns API changes are released.

Motivation

MT-22401

Port the Email Campaigns public API (MT-21113) to the Node.js SDK. The MCP server's campaigns tools depend on this landing and being released to npm.

Changes

• Add client.emailCampaigns covering the full contract: getList (page-token pagination + search), get, create, update, delete (204 → void), the five lifecycle actions (start, schedule, cancel, terminate, reset), and getStats with an optional date range
• Types follow the published OpenAPI schema: flat request bodies, {data} response envelopes (Webhooks convention), UUID mailsend_domain_id, rapid/gradual delivery modes, 10-value CampaignState, audience id arrays, TemplateAttributes (subject required on create) with body_html/body_text/merge_tags, per-recipient state-metadata errors
• Full-lifecycle example in examples/email-campaigns/everything.ts + README bullet

How to test

• Run examples/email-campaigns/everything.ts with a real API token and a verified sending domain — create a draft, update design/audience, schedule + cancel, fetch stats, delete
• Verify a lifecycle 422 (e.g. cancel on a draft) surfaces the API error message

Summary by CodeRabbit

• New Features

  • Added email campaign management, including creation, editing, scheduling, sending, cancellation, termination, reset, and deletion.
  • Added campaign performance statistics with optional date filtering.
  • Added typed support for campaign states, templates, delivery options, pagination, and lifecycle responses.

• Documentation

  • Added an end-to-end email campaigns workflow example.

• Tests

  • Added coverage for campaign operations, requests, responses, and error handling.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a typed Email Campaigns API with CRUD, lifecycle actions, scheduling, termination, reset, statistics, MailtrapClient exposure, Axios-mock tests, and an end-to-end example documented in the README.

Changes

Email campaigns integration

Layer / File(s)	Summary
Campaign contracts and resource operations src/types/api/email-campaigns.ts, src/lib/api/resources/EmailCampaigns.ts, src/__tests__/lib/api/resources/EmailCampaigns.test.ts	Defines campaign entities, request parameters, responses, lifecycle states, and statistics. Implements and tests the corresponding Axios endpoints.
MailtrapClient exposure src/lib/MailtrapClient.ts, src/lib/api/EmailCampaigns.ts, src/__tests__/lib/api/EmailCampaigns.test.ts	Adds the emailCampaigns getter and binds the resource operations through the base API using the shared Axios instance.
End-to-end usage example examples/email-campaigns/everything.ts, README.md	Adds a complete campaign workflow and links it from the supported examples list.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MailtrapClient
  participant EmailCampaignsBaseAPI
  participant EmailCampaignsApi
  participant MailtrapAPI
  Client->>MailtrapClient: access emailCampaigns
  MailtrapClient->>EmailCampaignsBaseAPI: construct accessor with shared Axios instance
  EmailCampaignsBaseAPI->>EmailCampaignsApi: bind campaign methods
  EmailCampaignsApi->>MailtrapAPI: send CRUD or lifecycle request
  MailtrapAPI-->>EmailCampaignsApi: return campaign, stats, or error

Loading

Possibly related PRs

• mailtrap/mailtrap-nodejs#64: Adds a similar API resource integration with client access, wrappers, types, tests, and a lifecycle example.
• mailtrap/mailtrap-nodejs#65: Adds another typed API resource with CRUD methods, client access, examples, and tests.
• mailtrap/mailtrap-nodejs#117: Adds a MailtrapClient API module with resource wrappers, typed models, examples, and tests.

Suggested labels: feature request

Suggested reviewers: igordobryn, piobeny

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and specifically identifies the main change: adding the Email Campaigns API to the SDK.
Description check	✅ Passed	The description provides motivation, comprehensive change list, testing instructions, and follows the required template structure with all essential sections completed.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Rabsztok]

Applied the same fix CodeRabbit raised on the Python PR: client.emailCampaigns no longer calls validateAccountIdPresence() — the endpoint is token-scoped (matches the inbound getter precedent), and the example no longer configures accountId. Full suite (410 tests) + lint green.