Document the content review before a campaign starts sending

[oshchyhol]

Motivation

Campaign content is going to be reviewed when a campaign is scheduled, not when it starts sending. A campaign the review holds is caught before its time, while the sender can still edit or cancel it, and a campaign that passed starts on time. This changes what the start, schedule and cancel endpoints return, so the docs need to follow.

Keep this as a draft until the change is live: docs.mailtrap.io publishes main right away.

Changes

All in specs/email-campaigns.openapi.yml.

• start: the campaign is reviewed first, so the response shows it scheduled with scheduled_at about five minutes ahead, and it becomes started at that time. A hold moves it to under_review meanwhile
• schedule and EmailCampaignScheduleRequest.datetime: the time must be at least 5 minutes ahead (was "in the future"); the sample comments in every language say the same
• cancel: also allowed for a campaign under_review that was held while scheduled. A campaign held after sending started returns 422 "Campaign is under review and cannot be cancelled"
• current_state: what under_review means, what happens after approval, and the draft a campaign returns to when the review did not finish in time
• current_state_metadata.reason gets a description with review_not_verified_in_time; scheduled_at is also present in under_review for a campaign held while scheduled

How to test

• open https://editor.swagger.io → File → Import URL → https://raw.githubusercontent.com/mailtrap/mailtrap-openapi/campaign-review-on-schedule/specs/email-campaigns.openapi.yml
• Start an email campaign: the description says the campaign is reviewed first and stays scheduled about five minutes
• Schedule an email campaign: the description and every code sample say at least 5 minutes ahead
• Cancel a scheduled email campaign: lists both 422 messages
• the EmailCampaign schema: current_state, current_state_metadata.reason and scheduled_at show the new descriptions

Images and GIFs

N/A

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7e4a5682-fc40-4225-ad22-91215681e3ff

• Autopilot · 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.}