MT-22401: Add Email Campaigns API

[Rabsztok]

Motivation

https://railsware.atlassian.net/browse/MT-22401

Port the Email Campaigns public API (MT-21113) to the Ruby SDK.

Changes

• Add Mailtrap::EmailCampaignsAPI covering the full contract: list (page-token pagination + name filter), get, create, update, delete, the five lifecycle actions (start, schedule, cancel, terminate, reset), and stats with an optional date range
• Add Mailtrap::EmailCampaign / EmailCampaignStats / EmailCampaignsListResponse DTOs matching the OpenAPI schema (audience ids, template with body_html/body_text/merge_tags, 10-state lifecycle)
• Requests send flat JSON bodies and single-object responses unwrap the data envelope, per the published spec; delete returns nil on 204
• Runnable walkthrough in examples/email_campaigns_api.rb + README "Email marketing" entry

How to test

• Run examples/email_campaigns_api.rb with a real API token and a verified sending domain — create a draft campaign, update its design, schedule + cancel it, fetch stats, delete it
• Verify responses deserialize with populated attributes (campaign id, current_state, template fields)

Summary by CodeRabbit

• New Features

  • Added Email Campaigns API support for creating, listing, retrieving, updating, and deleting campaigns.
  • Added campaign lifecycle actions, including scheduling, starting, canceling, terminating, and resetting campaigns.
  • Added campaign performance statistics with optional date-range filtering.
  • Added a complete Ruby usage example and documentation entry for Email Campaigns.

• Tests

  • Added coverage for campaign data handling, API operations, lifecycle transitions, validation, errors, and statistics.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds typed email campaign entities and a Mailtrap::EmailCampaignsAPI wrapper supporting CRUD, lifecycle actions, pagination, filtering, and statistics retrieval, with request specs and a documented end-to-end example.

Changes

Email Campaigns API

Layer / File(s)	Summary
Campaign response contracts lib/mailtrap/email_campaign.rb, spec/mailtrap/email_campaign_spec.rb	Defines campaign, statistics, and paginated-list DTOs and verifies populated and omitted attributes.
Campaign API operations lib/mailtrap/email_campaigns_api.rb, lib/mailtrap.rb, spec/mailtrap/email_campaigns_api_spec.rb	Implements campaign CRUD, lifecycle actions, date-filtered statistics, response conversion, and API error handling with HTTP request coverage.
Campaign usage example examples/email_campaigns_api.rb, README.md	Adds an end-to-end campaign API example and links it from the supported functionality section.

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

Suggested reviewers: i7an, igordobryn

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the Email Campaigns API.
Description check	✅ Passed	It includes Motivation, Changes, and How to test; only the optional Images and GIFs section is missing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch MT-22401-ruby-email-campaigns

---

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

[coderabbitai]

🧹 Nitpick comments (1)

lib/mailtrap/email_campaigns_api.rb (1)

104-110: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Fix YARD @return tag format for delete.

# @return nil (Line 106) should be # @return [nil] to match the @return [Type] description convention used by every other method in this file, so YARD parses the return type correctly.

📝 Proposed fix

     # Deletes an email campaign. The campaign must not be in a sending state.
     # `@param` email_campaign_id [Integer] The email campaign ID
-    # `@return` nil
+    # `@return` [nil]
     # @!macro api_errors
     def delete(email_campaign_id)

🤖 Prompt for 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.

In `@lib/mailtrap/email_campaigns_api.rb` around lines 104 - 110, Update the YARD
documentation for the delete method so its `@return` annotation uses the bracketed
type format [nil], matching the convention used throughout the file; leave the
delete implementation unchanged.

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

Nitpick comments:
In `@lib/mailtrap/email_campaigns_api.rb`:
- Around line 104-110: Update the YARD documentation for the delete method so
its `@return` annotation uses the bracketed type format [nil], matching the
convention used throughout the file; leave the delete implementation unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 618f5e87-eb29-4288-a78d-8517b08aaaf8

📥 Commits

Reviewing files that changed from the base of the PR and between 484d54c and 82b542c.

📒 Files selected for processing (7)

• README.md
• examples/email_campaigns_api.rb
• lib/mailtrap.rb
• lib/mailtrap/email_campaign.rb
• lib/mailtrap/email_campaigns_api.rb
• spec/mailtrap/email_campaign_spec.rb
• spec/mailtrap/email_campaigns_api_spec.rb