Add Email Campaigns API documentation#43
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 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 API-key and bearer authentication schemes, page-token pagination, request/response schemas with lifecycle state metadata, and standardized error handling with rate-limit headers. 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 inconclusive)
✅ 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
Bring the public Email Campaigns spec in line with the api/v2/email_campaigns and api/v2/email_campaigns/stats controllers: - Flat request bodies (drop the `email_campaign` wrapper key) - create returns 201, delete returns 204 No Content - Wrap single/list/stats responses in a `data` envelope - Document the 429 rate-limited response (150 req / 10s) - Add start_date/end_date query params to the stats endpoint - Fix current_state and delivery_mode enums to the real values - Correct the `type` discriminator and current_state_metadata shapes (errors as objects, scheduled_at as a unix timestamp) - Drop fields the public API does not return (audience_defined, stats)
Rabsztok
force-pushed
the
MT-22365-write-email-campaigns-endpoint-documentation
branch
from
cd860c8 to
9acdeae
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
specs/email-campaigns.openapi.yml (1)
55-60:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftComplete
x-codeSamplesset and switch API key usage to env vars.All operations still expose only cURL samples, and token headers are not env-var based. This does not follow the required sample matrix and key-handling convention for OpenAPI specs in this repo.
As per coding guidelines, “Include code samples in OpenAPI specs in this priority order: cURL (shell), Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java” and “Use environment variables for API keys in code samples (e.g., process.env.MAILTRAP_API_KEY)”.
Also applies to: 87-105, 127-131, 163-172, 197-201, 235-239
🤖 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 55 - 60, The x-codeSamples blocks in the email-campaigns.openapi.yml file currently only contain cURL examples with hardcoded API tokens. You need to expand each x-codeSamples block (located at the specified line ranges: 55-60, 87-105, 127-131, 163-172, 197-201, 235-239) to include code samples for all seven languages in priority order: cURL (shell), Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), and Java. For the existing cURL sample, replace the hardcoded token value with an environment variable reference (e.g., $MAILTRAP_API_TOKEN). Apply the same environment variable pattern to all new language samples you add, ensuring API keys are consistently retrieved from environment variables across all code examples rather than being hardcoded strings.Source: Coding guidelines
🤖 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 485-489: The scheduled_at field in the email campaigns OpenAPI
spec has a type mismatch with the PR requirements. Currently, the scheduled_at
field under current_state_metadata is defined with type string and format
date-time (ISO 8601), but it should be defined as a unix timestamp instead.
Change the type from string to integer, update the format to int64 (or remove
the format entirely for unix timestamps), modify the description to indicate it
represents a unix timestamp, and update the example value from the ISO 8601
datetime string to a corresponding unix timestamp number to align with the
actual API contract change.
---
Duplicate comments:
In `@specs/email-campaigns.openapi.yml`:
- Around line 55-60: The x-codeSamples blocks in the email-campaigns.openapi.yml
file currently only contain cURL examples with hardcoded API tokens. You need to
expand each x-codeSamples block (located at the specified line ranges: 55-60,
87-105, 127-131, 163-172, 197-201, 235-239) to include code samples for all
seven languages in priority order: cURL (shell), Node.js (JavaScript), PHP,
Python, Ruby, .NET (C#), and Java. For the existing cURL sample, replace the
hardcoded token value with an environment variable reference (e.g.,
$MAILTRAP_API_TOKEN). Apply the same environment variable pattern to all new
language samples you add, ensuring API keys are consistently retrieved from
environment variables across all code examples rather than being hardcoded
strings.
🪄 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: 69914325-f85d-43b6-b665-62b75adc5b2e
📒 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