[Rabsztok]

Motivation

The API gets an endpoint for the aggregated Email Marketing stats (campaigns and automations), the numbers shown on Email Marketing > Stats Overview. Campaign and automation traffic is no longer counted under GET /api/stats, which now covers the Email API/SMTP streams only. This PR documents both sides of that split.

Changes

• GET /api/marketing/stats is documented under a new Marketing Stats page: required start_date/end_date, optional sending_domain_ids[], sources[] (campaigns/automations) and email_service_providers[], returning {data: {...}} with 13 counts and rates

  • one sources[] value narrows to that source; none or both mean all Email Marketing traffic
  • open/click/spam/unsubscription rates divide by delivery_count, unlike the per-campaign stats endpoint, which divides every rate by sent_count; the description says so, so the two don't seem to disagree
  • 400 lists the four validation messages, 403 covers tokens limited to sending domains or sandboxes, and 429 documents both limits (10/min per account on this endpoint, plus the global throttle), which return different keys
  • samples in cURL and all seven SDKs, querying the last 30 days and computing the dates at runtime

• the stats domain filter is documented as sending_domain_ids[], the name the API reads; domain_ids[] was silently ignored, so filtered requests returned every domain

• the sending domain in the GET /api/stats/domains items, the email log responses and the email logs filter is documented as sending_domain_id, the name the API returns and reads; filters[domain_id] was dropped, so filtered requests returned every domain's logs

• the sending_streams[] description says that omitting it means both API/SMTP streams, and points campaign and automation traffic to the new endpoint

⚠️ Hold the merge until the API change is live. Every SDK has released its marketing stats method, and the samples match those releases: Node.js 6.0.0, PHP 3.17.0, Python 3.0.0, Ruby 2.19.0, .NET 3.9.0, Java 1.10.0 and Go 0.5.0. mailtrap-go still reads the domain ID from domain_id, so its DomainStats.DomainID (printed by the Go by-domain sample) and EmailLogMessage.DomainID stay 0 until its fix ships.

How to test

You'll need an API token with viewer or admin access to an account that sends campaigns and automations, plus a second token limited to one sending domain.

• Docs page: the GitBook preview has a Marketing Stats page with request/response examples and all eight sample tabs
• Totals: run the cURL sample without sources[]. Expect 200 with data holding exactly the 13 fields, matching Email Marketing > Stats Overview for the same 30 days
• Sources: sources[]=campaigns and sources[]=automations each match the Source select on that page, and the two add up to the unfiltered totals
• Filters: sending_domain_ids[]=<id> and email_service_providers[]=Google narrow the totals
• No data: a range with no sends returns every count and rate as 0
• 400s: no start_date, end_date=2026-13-01, an unknown sending domain id, sources[]=newsletters. Each returns the errors message documented on the 400 response
• 403: the domain-limited token gets 403 {"errors":"Access forbidden"}
• 429: the 11th request within a minute returns {"errors":"Rate limit exceeded"}, while GET /api/stats still answers
• GET /api/stats domain filter: sending_domain_ids[]=<id> returns only that domain's numbers
• sending_domain_id: each GET /api/stats/domains item and each email log has sending_domain_id, and GET /api/email_logs with filters[sending_domain_id][operator]=equal&filters[sending_domain_id][value][]=<id> returns only that domain's logs

Summary by CodeRabbit

• Documentation
  • Documented a marketing statistics endpoint for combined campaign and automation metrics, including date and optional filters, response and validation details, rate limits, and client examples.
  • Clarified that email sending statistics cover Email API/SMTP traffic, while campaign and automation traffic is reported separately.
  • Updated all five email sending statistics endpoints to use sending_domain_ids[] instead of domain_ids[], with access and default-filter behavior documented.
  • Updated campaign statistics example rates.

[coderabbitai]

No actionable comments were generated in the recent review.

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 84b58ffd-68ef-4c28-8c1b-b0eb523f16dd

📥 Commits

Reviewing files that changed from the base of the PR and between 4e2f059 and 494a410.

📒 Files selected for processing (2)

• specs/email-campaigns.openapi.yml
• specs/email-sending.openapi.yml

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The OpenAPI specifications add GET /api/marketing/stats for campaign and automation metrics. They also rename the sending-domain filter used by Email API statistics and clarify which traffic each statistics endpoint covers.

Changes: Email statistics

Layer / File(s)	Summary
Marketing stats endpoint specs/email-campaigns.openapi.yml	Documents the endpoint, its required date filters, optional domain, source, and provider filters, and access and rate limits.
Marketing metrics and responses specs/email-campaigns.openapi.yml	Defines the metrics and their rate denominators, updates campaign-stat example values, and documents success, validation, and rate-limit response bodies.
Email API statistics filters specs/email-sending.openapi.yml	Uses sending_domain_ids[] across the five statistics endpoints. Clarifies domain access, filter defaults, and the separation of Email API/SMTP traffic from campaign and automation traffic.

Priority: Normal

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

Change: Other

Suggested reviewers: mklocek

Merge Risk: Minimal · up to 494a4

No actionable documentation defect is established. Confirm that the API change and SDK methods are live before merging, as the PR requests.

Architecture risk: Low · up to 494a4

The change affects 1 system.

Changed systems: specs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — specs (service) was modified; 2 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in specs/email-campaigns.openapi.yml: The document description now covers retrieving Email Marketing statistics as well as campaign and Email Marketing statistics.
• observed — Modified behavior in specs/email-campaigns.openapi.yml: Adds the Marketing Stats tag and its title, page description, and tag description.
• observed — Modified behavior in specs/email-campaigns.openapi.yml: Completes the existing campaign-stats Go example; the new account-level statistics endpoint begins immediately afterward.
• observed — Modified behavior in specs/email-campaigns.openapi.yml: Adds GET /api/marketing/stats for aggregated Email Marketing metrics across campaigns and automations. It documents rate denominators, viewer-level account access, exclusion of Email API/SMTP traffic, and a 10-requests-per-minute account limit separate from GET /api/stats. The endpoint requires start and end dates, accepts optional domain, source, and provider filters, and specifies success, validation, authentication, permission, and rate-limit responses, with examples in eight languages.

Pre-merge checks: 4

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title "Document GET /api/marketing/stats" matches the main change. The PR adds documentation for the new aggregated Email Marketing stats endpoint and also documents the split from GET /api/stats.…
Description check		The pull request includes the required Motivation, Changes, and How to test sections. It provides detailed scope, API behavior, examples, prerequisites, and test cases. The Images and GIFs section is …

Full details: Title check

Explanation

The title "Document GET /api/marketing/stats" matches the main change. The PR adds documentation for the new aggregated Email Marketing stats endpoint and also documents the split from GET /api/stats. The title is specific and short. It does not mention the sending_domain_ids[] rename or the GET /api/stats split, but those are secondary.

Full details: Description check

Explanation

The pull request includes the required Motivation, Changes, and How to test sections. It provides detailed scope, API behavior, examples, prerequisites, and test cases. The Images and GIFs section is missing, but this is non-critical because the changes are API documentation only.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.