[Rabsztok]

Motivation

Several error responses in the Account Management, Email Campaigns and Email Sending references don't match what the API returns. Some 422 bodies have a different errors shape, three operations don't list their 422 at all, and a campaign's from_display_name can be null. Clients generated from these documents decode those responses wrongly.

Changes

• Account Management
  • Bulk permission updates return errors as a single message.
  • Creating an API token returns either messages per attribute (the token's own validation, such as no permissions or the active-token limit) or a single message (an invalid permission, such as an unknown resource). It is documented as a oneOf with an example of each.
  • Creating a sub account returns errors as an array of messages.
  • Deleting an account access lists its 422: the account owner's access can't be removed.
• Email Campaigns
  • Start and schedule get their own 422: a single message (an invalid transition or datetime) or sending-validation messages per attribute, campaign-wide ones under base. The documented array never occurs.
  • Cancel, terminate and reset keep the shared 422, narrowed to a single message.
  • Listing campaigns lists its 422 for an out-of-range token, as listing templates already does.
  • from_display_name is null for a campaign without a sender name.
• Email Sending
  • Domain setup instructions return one message per key (email or base), not arrays.
  • Deleting a domain lists its 422 for a domain that inbound inboxes still use.

This touches the same responses: blocks as #71 and sits next to the code samples #69 edits; whichever lands second rebases.

How to test

You'll need an admin API token for an account with a sending domain and email campaigns, and an organization API token for the sub-account checks. Each response below should match what the API reference now documents for that operation.

Account Management

• Owner permissions: PUT /api/account_accesses/{owner_access_id}/permissions/bulk with any permission. Expect 422, {"errors":"You can't update the permissions of an account owner"}.
• Token without permissions: POST /api/api_tokens with an empty resources list. Expect 422, {"errors":{"base":["No permissions selected. Please choose at least one."]}}.
• Token with an unknown resource: POST /api/api_tokens with {"resource_type":"project","resource_id":<missing id>,"access_level":100} in resources. Expect 422, {"errors":"Resource of type 'project' and ID #<id> not found"}.
• Owner access delete: DELETE /api/account_accesses/{owner_access_id}. Expect 422, {"errors":"You can not remove the owner of the account"}.
• Sub-account limit: POST /api/organizations/{organization_id}/sub_accounts for an organization at its sub-account limit. Expect 422, {"errors":["Accounts limit reached"]}. A name over 80 characters returns {"errors":["Failed to create account."]}.

Email Campaigns

• Start, sending validation fails: POST /api/email_campaigns/{id}/start on a draft of an account with no company information. Expect 422 with the message under errors.base as an array.
• Start, invalid transition: start a campaign that is already started. Expect 422, {"errors":"Cannot transition from 'started' to 'scheduled'"}.
• Schedule: the same two cases on POST /api/email_campaigns/{id}/schedule give the same two shapes.
• Cancel, terminate, reset: each from a state that doesn't allow it returns a single message, e.g. cancelling a draft gives {"errors":"Campaign is not scheduled"}.
• List, token out of range: GET /api/email_campaigns?per_page=100&token=100000000000000000. Expect 422, {"errors":"token is out of range"}.
• No sender name: GET /api/email_campaigns/{id} for a campaign created without from_display_name. Expect 200 with "from_display_name": null.

Email Sending

• Setup instructions, invalid email: POST /api/domains/{domain_id}/send_setup_instructions with {"email":"invalid"}. Expect 422, {"errors":{"email":"Invalid email address"}}.
• Domain delete, inbound inbox uses it: DELETE /api/domains/{domain_id} for a domain an inbound inbox depends on. Expect 422, {"errors":{"base":["Can't delete the domain because there are inbound inboxes depending on it."]}}.

Summary by CodeRabbit

• Documentation
  • Expanded API documentation with specific 422 error cases for account management, including permission changes, token creation, and sub-account creation.
  • Clarified email campaign validation responses for pagination, sending, and lifecycle actions, and documented nullable sender display names.
  • Added email-sending error details for invalid setup addresses, blocked domains, and domains that cannot be deleted while inbound inboxes depend on them.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

No actionable comments were generated in the recent review.

Walkthrough

The OpenAPI specifications add endpoint-specific error responses, examples, and schema details for account management, email campaigns, and email sending. Campaign documentation also updates the from_display_name field to allow null.

Changes: Account management

Layer / File(s)	Summary
Account access error responses specs/account-management.openapi.yml	Account-access deletion and permission updates document 422 failure cases and examples.
Token and sub-account error responses specs/account-management.openapi.yml	API-token and sub-account creation document endpoint-specific 422 schemas and examples.

Email campaigns

Layer / File(s)	Summary
Campaign action error contracts specs/email-campaigns.openapi.yml	Start and schedule use a sending-specific error response. The sending error schema supports a string or an object with arrays of messages; lifecycle errors have a separate schema.
Campaign list and response fields specs/email-campaigns.openapi.yml	The list endpoint documents a 422 response for an overflowing pagination offset. from_display_name allows null when no display name is set.

Email sending

Layer / File(s)	Summary
Domain and setup-instruction errors specs/email-sending.openapi.yml	Domain deletion documents the inbound-inbox dependency that blocks deletion. Setup instructions document invalid email and blocked-domain errors with string-valued errors entries.

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Other

Suggested reviewers: mklocek, izikaj, oshchyhol

Merge Risk: Minimal · previous review 4e681

This PR updates API documentation for 422 error bodies and the nullable sender name. It does not change runtime behavior, and no merge-blocking issues remain.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title names the two main themes of the PR: correcting the documented 422 error bodies across the API references and documenting the nullable campaign sender name. The changeset covers Account Mana…
Description check		The description follows the template. It has a Motivation section explaining that several error responses do not match the API. It has a Changes section grouped by the three specs, with each item stat…
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.

Full details: Title check

Explanation

The title names the two main themes of the PR: correcting the documented 422 error bodies across the API references and documenting the nullable campaign sender name. The changeset covers Account Management, Email Campaigns, and Email Sending specs, and the title is specific enough to identify the primary change without listing files. It is a single sentence of 11 words.

Full details: Description check

Explanation

The description follows the template. It has a Motivation section explaining that several error responses do not match the API. It has a Changes section grouped by the three specs, with each item stating the documented change. It has a How to test section with checkbox items and concrete requests and expected responses. The template's Images and GIFs section is missing. That section fits a visual change, and this PR changes only OpenAPI documentation, so its absence is not critical.

• 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

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: ba13cf32-00c1-41ef-a6e3-34eb5dfacbf9

Commits

Reviewing files that changed from the base of the PR and between ac255aa and 4e6814d.

Files selected for processing: 3

• specs/account-management.openapi.yml
• 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.

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