Add Email Campaigns API documentation#43
Conversation
📝 WalkthroughWalkthroughA new OpenAPI 3.1 specification for the Email Campaigns API is added with six endpoints for campaign CRUD and statistics retrieval. The specification includes authentication schemes, pagination, request/response schemas, and standardized error handling. README is updated to register the specification. ChangesEmail Campaigns OpenAPI Specification Addition
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 `@specs/email-campaigns.openapi.yml`:
- Around line 59-64: The x-codeSamples block currently contains only a cURL
sample; add additional samples for Node.js (JavaScript), PHP, Python, Ruby, .NET
(C#), and Java in the same x-codeSamples array for the same endpoint so all
required languages are present in the prescribed priority (shell, javascript,
php, python, ruby, csharp, java); for Node.js and SDK-supported languages use
the official Mailtrap SDK calls with environment-variable tokens (e.g.,
process.env.MAILTRAP_API_TOKEN) and for unsupported SDK methods include a brief
comment noting the limitation and provide a vanilla HTTP example; update every
x-codeSamples occurrence (the existing x-codeSamples block and the other
occurrences mentioned) to follow this pattern and keep the lang labels matching
the required names and the source fields populated accordingly.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro
Run ID: b6988521-6c51-4b6a-a830-4d262e4fae98
📒 Files selected for processing (2)
README.mdspecs/email-campaigns.openapi.yml
| x-codeSamples: | ||
| - lang: shell | ||
| label: 'cURL' | ||
| source: | | ||
| curl -X GET "https://mailtrap.io/api/email_campaigns?per_page=50&token=1" \ | ||
| -H 'Api-Token: YOUR_API_TOKEN' |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift
Add code samples for all required languages.
All endpoints currently provide only cURL samples. As per coding guidelines, x-codeSamples must include all languages in this priority order: cURL (shell), Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java. Missing samples reduce documentation completeness and user experience.
For Node.js and other SDK-supported languages, use official Mailtrap SDKs with environment variable references (e.g., process.env.MAILTRAP_API_TOKEN). If the SDK doesn't support a method, use GitBook generation or add a comment noting SDK limitations.
As per coding guidelines and retrieved learnings, x-codeSamples should include samples for: Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), and Java in addition to the existing cURL samples.
Also applies to: 89-109, 128-133, 162-174, 196-201, 226-231
🧰 Tools
🪛 Betterleaks (1.3.1)
[high] 63-64: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
🤖 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 `@specs/email-campaigns.openapi.yml` around lines 59 - 64, The x-codeSamples
block currently contains only a cURL sample; add additional samples for Node.js
(JavaScript), PHP, Python, Ruby, .NET (C#), and Java in the same x-codeSamples
array for the same endpoint so all required languages are present in the
prescribed priority (shell, javascript, php, python, ruby, csharp, java); for
Node.js and SDK-supported languages use the official Mailtrap SDK calls with
environment-variable tokens (e.g., process.env.MAILTRAP_API_TOKEN) and for
unsupported SDK methods include a brief comment noting the limitation and
provide a vanilla HTTP example; update every x-codeSamples occurrence (the
existing x-codeSamples block and the other occurrences mentioned) to follow this
pattern and keep the lang labels matching the required names and the source
fields populated accordingly.
There was a problem hiding this comment.
I will add code samples once it's implemented in the SDK:
https://railsware.atlassian.net/browse/MT-22401
There was a problem hiding this comment.
@Rabsztok, understood! That makes sense — it's better to add SDK-based samples once the feature is fully supported rather than providing placeholder or unsupported examples.
Would you like me to open a GitHub issue on this repository to track the follow-up work of adding code samples once MT-22401 is implemented? That way it won't be forgotten after this PR merges.
🧠 Learnings used
Learnt from: dr-3lo
Repo: mailtrap/mailtrap-openapi PR: 9
File: specs/email-sending-bulk.openapi.yml:159-170
Timestamp: 2025-12-29T15:56:56.076Z
Learning: In OpenAPI spec files under specs, particularly within x-codeSamples code examples, replace actual environment variable references with clear placeholders (e.g., YOUR_API_KEY, YOUR_ACCOUNT_ID) to avoid leaking secrets in documentation. Ensure code samples show substitute values and note how users should provide real values in their environment.
Learnt from: mklocek
Repo: mailtrap/mailtrap-openapi PR: 16
File: specs/sandbox.openapi.yml:116-127
Timestamp: 2026-01-28T15:18:12.895Z
Learning: For OpenAPI specs located under specs/, populate the x-codeSamples extension with samples in this exact priority: 1) curl (shell), 2) Node.js (JavaScript), 3) PHP, 4) Python, 5) Ruby, 6) .NET (C#), 7) Java. curl should always be the default first option to align with Mailtrap's in-app integration samples.
| x-page-title: Email Campaigns | ||
| x-page-description: Manage email marketing campaigns and their statistics | ||
|
|
||
| - name: Email Campaigns |
There was a problem hiding this comment.
previous tag had almost the same name
There was a problem hiding this comment.
It's a parent tag, so the menu should show something like:
Email Campaigns
- Email Campaigns
- Campaign Stats
Maybe it'd be better to create more general "Marketing" tag... What do you think?
There was a problem hiding this comment.
Marketing would better align with MT products
There was a problem hiding this comment.
Btw, there is Promotional at the moment. So, maybe that's the place
There was a problem hiding this comment.
Promotional is not a tag in the specs, but a custom category created in gitbook. I've rolled back the marketing rename, and removed email-campaigns parent level tag, so the end result in the menu looks like this:
What do you think @IgorDobryn ?
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/marketing.openapi.yml (1)
1-1:⚠️ Potential issue | 🟠 Major | ⚡ Quick winSpec registration path appears out of sync with repository docs.
This file is
specs/marketing.openapi.yml, but the repository listing context still points Email Campaigns tospecs/email-campaigns.openapi.yml. If unchanged, discoverability and tooling references will break for this spec.🤖 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 `@specs/marketing.openapi.yml` at line 1, The spec registration reference is out of sync: either update the repository/docs/tooling entries that point to "specs/email-campaigns.openapi.yml" to instead reference "specs/marketing.openapi.yml", or rename the spec file back to "specs/email-campaigns.openapi.yml" so the registration matches; search for occurrences of "specs/email-campaigns.openapi.yml" in the docs/config (spec registration/index listings, CI/spec tooling configs) and update them to the correct filename ("specs/marketing.openapi.yml") to restore discoverability.
🤖 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 `@specs/marketing.openapi.yml`:
- Around line 63-64: The cURL samples currently embed a placeholder API token in
the URL and header; update each cURL block (e.g., the GET sample containing curl
-X GET "https://mailtrap.io/api/email_campaigns?per_page=50&token=1" and the -H
'Api-Token: YOUR_API_TOKEN' header) to use an environment variable instead:
remove the token query parameter from the URL and replace the header value with
the env var $MAILTRAP_API_TOKEN (e.g., -H "Api-Token: $MAILTRAP_API_TOKEN");
apply the same change consistently to the other cURL blocks mentioned (the
blocks around the other locations in the comment).
---
Outside diff comments:
In `@specs/marketing.openapi.yml`:
- Line 1: The spec registration reference is out of sync: either update the
repository/docs/tooling entries that point to
"specs/email-campaigns.openapi.yml" to instead reference
"specs/marketing.openapi.yml", or rename the spec file back to
"specs/email-campaigns.openapi.yml" so the registration matches; search for
occurrences of "specs/email-campaigns.openapi.yml" in the docs/config (spec
registration/index listings, CI/spec tooling configs) and update them to the
correct filename ("specs/marketing.openapi.yml") to restore discoverability.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro
Run ID: fb56e5f3-6f55-44f3-b0c5-ad9b0f7eaf6d
📒 Files selected for processing (1)
specs/marketing.openapi.yml
Rabsztok
force-pushed
the
MT-22365-write-email-campaigns-endpoint-documentation
branch
from
0abbcf4 to
4ad75a1
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
specs/marketing.openapi.yml (2)
59-61:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDocument SDK limitation when only cURL samples are present.
Each operation currently exposes only
shellsamples. Per repo rules, either provide samples in the required language order or add an explicit limitation note when SDK methods are not yet supported (e.g., MT-22401), so this spec remains guideline-compliant.As per coding guidelines: "Use official Mailtrap SDKs for language-specific code examples in x-codeSamples; if SDK doesn't support a method, use GitBook generation or add a comment noting SDK limitations" and "Include code samples in OpenAPI specs in this priority order: cURL (shell), Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java."
Also applies to: 89-91, 128-130, 162-164, 196-198, 226-228
🤖 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 `@specs/marketing.openapi.yml` around lines 59 - 61, The operations currently only contain x-codeSamples with lang: shell and label: "cURL" (see x-codeSamples entries), which violates the repo's required sample priority; either add additional x-codeSamples in the required order (Node.js/JavaScript, PHP, Python, Ruby, .NET/C#, Java) for each operation, or add a clear limitation note referencing the tracker ID (e.g., MT-22401) indicating that SDK methods are not yet supported and so only cURL is provided; update each affected x-codeSamples block (the entries with lang: shell) and the corresponding operation description to include that limitation note if you cannot supply the SDK examples now.
63-64:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse environment-variable style API token in all cURL samples.
Api-Token: YOUR_API_TOKENshould be shown as an environment variable reference for consistency with docs standards.Suggested update pattern
- -H 'Api-Token: YOUR_API_TOKEN' + -H "Api-Token: $MAILTRAP_API_KEY"As per coding guidelines: "Use environment variables for API keys in code samples (e.g., process.env.MAILTRAP_API_KEY)."
Also applies to: 93-95, 132-133, 166-168, 200-201, 230-231
🤖 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 `@specs/marketing.openapi.yml` around lines 63 - 64, Replace the hard-coded API token in the cURL examples with an environment-variable style reference: update the Authorization header/Api-Token header occurrences (e.g., the cURL sample starting with curl -X GET "https://mailtrap.io/api/email_campaigns...") to use an env var placeholder like $MAILTRAP_API_TOKEN (and reference the token query param similarly if present) and apply the same replacement to the other cURL samples noted (the blocks around the other occurrences). Ensure the examples consistently use the env-var style token for both header and query-param usages.
🤖 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.
Duplicate comments:
In `@specs/marketing.openapi.yml`:
- Around line 59-61: The operations currently only contain x-codeSamples with
lang: shell and label: "cURL" (see x-codeSamples entries), which violates the
repo's required sample priority; either add additional x-codeSamples in the
required order (Node.js/JavaScript, PHP, Python, Ruby, .NET/C#, Java) for each
operation, or add a clear limitation note referencing the tracker ID (e.g.,
MT-22401) indicating that SDK methods are not yet supported and so only cURL is
provided; update each affected x-codeSamples block (the entries with lang:
shell) and the corresponding operation description to include that limitation
note if you cannot supply the SDK examples now.
- Around line 63-64: Replace the hard-coded API token in the cURL examples with
an environment-variable style reference: update the Authorization
header/Api-Token header occurrences (e.g., the cURL sample starting with curl -X
GET "https://mailtrap.io/api/email_campaigns...") to use an env var placeholder
like $MAILTRAP_API_TOKEN (and reference the token query param similarly if
present) and apply the same replacement to the other cURL samples noted (the
blocks around the other occurrences). Ensure the examples consistently use the
env-var style token for both header and query-param usages.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: fc93d92d-7fb8-4a05-9d38-ea70eed1f329
📒 Files selected for processing (2)
README.mdspecs/marketing.openapi.yml
✅ Files skipped from review due to trivial changes (1)
- README.md
Rabsztok
force-pushed
the
MT-22365-write-email-campaigns-endpoint-documentation
branch
from
4ad75a1 to
5cc92a8
Compare
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/email-campaigns.openapi.yml (1)
3-3:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse the official product name in the spec description.
Line 3 uses
email marketingas a generic phrase. Please capitalize it toEmail Marketingso the top-level docs stay consistent with the repo’s product naming rules.Suggested fix
- description: Manage email marketing campaigns and retrieve their performance statistics + description: Manage Email Marketing campaigns and retrieve their performance statisticsBased on learnings: Applies to **/*.openapi.yml : Use official product naming: 'Email API/SMTP' (can shorten to 'Email API' or 'API/SMTP'), 'Email Sandbox' (can shorten to 'Sandbox'), 'Email Marketing' (can shorten to 'Marketing')
🤖 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 `@specs/email-campaigns.openapi.yml` at line 3, Update the top-level OpenAPI description value to use the official product naming by capitalizing "Email Marketing" (change the string in the description field currently reading "email marketing" to "Email Marketing") in the specs email-campaigns OpenAPI document; search for other .openapi.yml files with similar top-level description fields and apply the same capitalization for consistency (use "Email API/SMTP", "Sandbox", or "Marketing" per repo naming rules where relevant).
🤖 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.
Outside diff comments:
In `@specs/email-campaigns.openapi.yml`:
- Line 3: Update the top-level OpenAPI description value to use the official
product naming by capitalizing "Email Marketing" (change the string in the
description field currently reading "email marketing" to "Email Marketing") in
the specs email-campaigns OpenAPI document; search for other .openapi.yml files
with similar top-level description fields and apply the same capitalization for
consistency (use "Email API/SMTP", "Sandbox", or "Marketing" per repo naming
rules where relevant).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: dbac05fa-e49f-4124-909c-b5678f6f88d2
📒 Files selected for processing (1)
specs/email-campaigns.openapi.yml
3 participants
Summary
Adds a new OpenAPI 3.1 specification documenting the Email Campaigns in Marketing API.
specs/marketing.openapi.ymlcovering the full campaign lifecycle:GET /api/email_campaigns— list campaignsPOST /api/email_campaigns— create a campaignGET /api/email_campaigns/{id}— retrieve a campaignPATCH /api/email_campaigns/{id}— update a campaignDELETE /api/email_campaigns/{id}— delete a campaignGET /api/email_campaigns/{id}/stats— retrieve aggregated campaign statisticsREADME.md(base URLhttps://mailtrap.io).Test plan
GitBook | MT QAaccount from 1password🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation