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), numeric domain_id (matching the Sending Domains endpoints ids), 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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 45cceddc-a1df-4c2c-82f0-ae511234c747

📥 Commits

Reviewing files that changed from the base of the PR and between 47c3416 and d5a81a9.

📒 Files selected for processing (1)

• examples/email-campaigns/everything.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• examples/email-campaigns/everything.ts

---

📝 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#66: Adds the README functionality-list entry that this change extends with the Email Campaigns example.
• mailtrap/mailtrap-nodejs#89: Adds another typed API resource with CRUD methods, client access, examples, and tests.

Suggested labels: feature request

Suggested reviewers: piobeny, igordobryn

🚥 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
Title check	✅ Passed	The title clearly and concisely identifies the primary change: adding the Email Campaigns API.
Description check	✅ Passed	The description covers motivation, changes, and testing steps; the optional Images and GIFs section is not included.
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.

✨ 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.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/email-campaigns/everything.ts`:
- Around line 62-66: Replace the hard-coded past datetime in the schedule call
with an execution-relative future time, and update the statistics request to
omit the fixed May 2026 filter or generate a window covering the campaign’s
actual send time. Preserve the subsequent cancellation, sending, termination,
statistics, and deletion flow in the example.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a6faa18b-135f-4a61-a765-a94f584cc216

📥 Commits

Reviewing files that changed from the base of the PR and between 85245f4 and 47c3416.

📒 Files selected for processing (8)

• README.md
• examples/email-campaigns/everything.ts
• src/__tests__/lib/api/EmailCampaigns.test.ts
• src/__tests__/lib/api/resources/EmailCampaigns.test.ts
• src/lib/MailtrapClient.ts
• src/lib/api/EmailCampaigns.ts
• src/lib/api/resources/EmailCampaigns.ts
• src/types/api/email-campaigns.ts

🚧 Files skipped from review as they are similar to previous changes (7)

• README.md
• src/tests/lib/api/EmailCampaigns.test.ts
• src/lib/MailtrapClient.ts
• src/lib/api/EmailCampaigns.ts
• src/tests/lib/api/resources/EmailCampaigns.test.ts
• src/types/api/email-campaigns.ts
• src/lib/api/resources/EmailCampaigns.ts