Enhance Email Logs API description with more details about multi-value filters

[mklocek]

Changes

• Enhance Email Logs API description with more details about multi-value filters

Summary by CodeRabbit

• New Features
  • Email log filtering now supports multiple values per filter using array syntax in query parameters
  • Enhanced with specialized filter types for more precise querying and control over email log data

[coderabbitai]

Warning

Rate limit exceeded

@mklocek has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 19 minutes and 42 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2fe2660d-26ff-49f3-8987-551af8a34d72

📥 Commits

Reviewing files that changed from the base of the PR and between 6ffeff0 and f66ae74.

📒 Files selected for processing (1)

• specs/email-sending.openapi.yml

📝 Walkthrough

Walkthrough

Refactored email logs filter schemas in OpenAPI specification to support array-valued parameters via bracket notation and introduced discriminated union types. Replaced scalar filter definitions with specialized, operator-aware filter schemas for strings, counts, and identifiers, updating all relevant references and examples throughout the specification.

Changes

Cohort / File(s)

Summary

Email Logs Filter Schema Refactoring specs/email-sending.openapi.yml

Restructured filter definitions to support array values and bracket notation. Introduced new discriminated union schemas (FilterCiString, FilterString) and specialized operator-aware schemas (FilterCiEqualString, FilterEqualString, FilterContainString, FilterEmptyString, FilterClicksCount, FilterOpensCount). Updated EmailLogsListFilters references to use new specialized filter schemas. Refined operator enums for count and identifier filters (equal, greater_than, less_than for counts; equal, not_equal for IDs). Updated examples and descriptions to reflect new shapes and query parameter conventions (ISO 8601 dates, bracket notation for arrays).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #19 — Introduces the original Filter* schemas that are being refactored and restructured in this PR with new discriminated union designs and expanded operator/value shapes.

Suggested reviewers

• leonid-shevtsov
• IgorDobryn
• GannaRW
• piobeny

Poem

🐰 Array filters now dance with grace,
Discriminated unions find their place,
Bracket notation hops along the way,
Email logs filter better, come what may!
Schema harmonies, no more dismay! 📧✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is largely incomplete, providing only a single bullet point that repeats the title without elaborating on the specific changes made, the motivation, testing approach, or how to verify the updates.	Complete the description by filling out the Motivation section, expanding the Changes section with details of the schema refactoring, and including a How to test section with verification steps.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: enhancing the Email Logs API description with details about multi-value filters, which is reflected in the comprehensive refactoring of filter schemas to support array values.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch email-logs-filters-improvement

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

specs/email-sending.openapi.yml (1)

2134-2167: Remove the dead helper schemas or wire them into the concrete filters.

FilterCiString, FilterCiOptionalString, FilterString, and FilterExactString are not referenced anywhere in this file, so they currently just expand the schema surface and leave the Spectral unused-component warnings unresolved. Either reuse them from the concrete filter types or drop them.

Also applies to: 2211-2224

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@specs/email-sending.openapi.yml` around lines 2134 - 2167, The schemas
FilterCiString, FilterCiOptionalString, FilterString, and FilterExactString are
unused and causing Spectral unused-component warnings; either remove these dead
helper schemas entirely or wire them into the concrete filter definitions (e.g.,
replace direct $ref targets in oneOf/discriminator mappings with references to
these helpers or update FilterCiOptionalString/FilterCiString to be referenced
by FilterCiEqualString/FilterCiContainString/FilterEmptyString mappings) so the
helpers are actually referenced; update discriminator mappings (propertyName
operator) and any oneOf arrays (e.g., in FilterCiOptionalString and
FilterCiString) to point to the helper schemas or delete the helper definitions
to eliminate the unused-component warnings.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1196-1200: The x-codeSamples extension for the OpenAPI operation
(operationId listEmailLogs) is missing multiple language samples; add an
x-codeSamples array containing seven entries in this exact priority: 1) curl
(shell) — keep the existing curl sample as the first item, 2) Node.js
(JavaScript) — use fetch or node-fetch to call the same GET URL with the
Authorization header, 3) PHP — show a curl_exec example, 4) Python — show
requests.get with headers and params, 5) Ruby — show Net::HTTP or HTTParty GET
with headers, 6) .NET (C#) — show HttpClient GET with Authorization header, and
7) Java — show OkHttp or HttpClient GET; ensure each sample uses the same query
parameters, includes the Authorization: Bearer YOUR_API_KEY header, and sets the
language and label fields consistently to match other specs under specs/.
- Around line 1211-1215: The filter documentation is ambiguous about how
multiple values are combined; update the shared filter description in
specs/email-sending.openapi.yml (the block that explains
filters[field][operator] and filters[field][value] and the repeated bracket
notation filters[field][value][]=...) to state the backend contract explicitly:
specify whether arrays are treated as OR (match any) or AND (match all) for
inclusion operators, and specify the semantics for negation operators (e.g.,
whether not_include_event with multiple values means "exclude any of these" or
"exclude all of these"), and then mirror or reference that single clear sentence
in both places currently using the bracket-notation example (the two blocks
around the existing bracket-notation text) so both occurrences use the exact
same wording.

---

Nitpick comments:
In `@specs/email-sending.openapi.yml`:
- Around line 2134-2167: The schemas FilterCiString, FilterCiOptionalString,
FilterString, and FilterExactString are unused and causing Spectral
unused-component warnings; either remove these dead helper schemas entirely or
wire them into the concrete filter definitions (e.g., replace direct $ref
targets in oneOf/discriminator mappings with references to these helpers or
update FilterCiOptionalString/FilterCiString to be referenced by
FilterCiEqualString/FilterCiContainString/FilterEmptyString mappings) so the
helpers are actually referenced; update discriminator mappings (propertyName
operator) and any oneOf arrays (e.g., in FilterCiOptionalString and
FilterCiString) to point to the helper schemas or delete the helper definitions
to eliminate the unused-component warnings.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3c32fe7e-5b81-4628-b0a4-548885de3d10

📥 Commits

Reviewing files that changed from the base of the PR and between 73a0136 and 6ffeff0.

📒 Files selected for processing (1)

• specs/email-sending.openapi.yml