SUP-1824: Update API Documentation

[ZairesDev]

Fixes #1824

Checklist

• Up to date with main
• All the tests are passing
• Delete all resources created in tests
• Prettier
• Spectral Lint
• npm run bundle outputs nothing suspect
• npm run postman outputs nothing suspect

Changes

This PR completes Update API Documentation from the Capital One MAAS mail_partition Batching plan. It adds comprehensive API documentation for the mail_partition field, enabling Capital One's MAAS (Marketing as a Service) program to use this field for separating mail into batches by pop_id for per-dealership USPS 3602 postage statements.

Request Schema Updates

• Added mail_partition field to resources/letters/models/letter_editable.yml
  • Optional (nullable) string field
  • Includes description explaining batching behavior, account restrictions, and feature flag requirement

Response Schema Updates

• Added mail_partition field to all letter response model variants:
  • resources/letters/models/no_extra_service.yml
  • resources/letters/models/registered.yml
  • resources/letters/models/certified.yml
• Ensures mail_parititon appears in API responses for accounts with the feature flag enabled

Request Examples

• Added mail_partition: "1076" to JSON request example in resources/letters/letters.yml (line 230)
• Added mail_partition: "1122" to form-urlencoded request example in resources/letters/letters.yml (line 282)
• Demonstrates proper usage with Capital One MAAS pop_id values

Response Examples

• Added mail_partition: "1076" to single letter response example (resources/letters/responses/letter.yml, line 96)
• Added mail_partition: "1076" to list response example (resources/letters/responses/all_letters.yml, line 101)

Feature Flag Documentation

• Added "Mail Sorting and Batching" section to Letters tag description in lob-api-public.yml (lines 1116-1120)
• Documents the Capital One MAAS use case
• Explains feature flag requirement (mail_partition LaunchDarkly feature flag)
• Notes account restrictions and provides contact information for access requests
• Warns about validation errors for unauthorized usage

Impact: This documentation-only change makes the mail_partition field publicly documented in the Lob API OpenAPI specification. The field enables customers with the appropriate feature flag to separate mail into batches, which is essential for Capital One's MAAS program requirements. All changes are backward compatible and only affect API documentation visibility.

[cursor]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on December 31.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[gemini-code-assist]

Summary of Changes

Hello @ZairesDev, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request primarily focuses on updating the API documentation to formally introduce and describe the mail_sort field. This field is designed to facilitate mail batching for specific use cases, notably for Capital One's MAAS program, enabling per-dealership USPS 3602 postage statements. The changes encompass schema updates for both requests and responses, inclusion of the field in various examples, and detailed explanations of its feature-flagged status and access requirements. These modifications are documentation-only and ensure backward compatibility, enhancing the clarity and usability of the API for relevant customers.

Highlights

• API Version Bump: The API version has been incremented from "1.20.8" to "1.20.9" in the bundled OpenAPI specification.
• Mail Sort Field Introduction: The mail_sort field has been formally introduced and documented across various request and response schemas.
• Comprehensive Documentation: Detailed descriptions for mail_sort have been added, explaining its purpose for mail batching, its use in the Capital One MAAS program, and its feature-flagged nature.
• Examples Updated: Request and response examples throughout the API documentation have been updated to include the mail_sort field with sample values.
• Feature Flag Details: Specific documentation regarding the mail_sort LaunchDarkly feature flag, account restrictions, and contact information for access requests has been added.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request does a great job of adding comprehensive API documentation for the new mail_sort field. The descriptions are clear and provide all the necessary context for developers.

My review includes a few suggestions to improve maintainability. The main point is to avoid duplicating the mail_sort schema definition across multiple files by extracting it into a reusable component. I've also noted an extraneous dependency in package-lock.json that should be cleaned up.

[burkematthew]

@ZairesDev now that we've changed the name of the field, we should change this as well.

[ZairesDev]

@ZairesDev now that we've changed the name of the field, we should change this as well.

I only set 'mail_partition' to the column within the letters table in the DB. As far as API requests/responses, I left that as mail_sort. That's why I didn't change any of this documentation.

[burkematthew]

@ZairesDev now that we've changed the name of the field, we should change this as well.

I only set 'mail_partition' to the column within the letters table in the DB. As far as API requests/responses, I left that as mail_sort. That's why I didn't change any of this documentation.

@ZairesDev we should change the input field to match what we're using in the DB. It's confusing to have a field called mail_sort that ultimately maps into mail_partition and where we have a virtual field called mail_sort that is different than what a user submits in that field.

[ZairesDev]

@ZairesDev now that we've changed the name of the field, we should change this as well.

I only set 'mail_partition' to the column within the letters table in the DB. As far as API requests/responses, I left that as mail_sort. That's why I didn't change any of this documentation.

@ZairesDev we should change the input field to match what we're using in the DB. It's confusing to have a field called mail_sort that ultimately maps into mail_partition and where we have a virtual field called mail_sort that is different than what a user submits in that field.

I concur. I'll also create a PR to update the entry-planning changes as well. Thanks for the review, as always, Matthew!

[Copilot]

Pull request overview

This PR adds comprehensive API documentation for the mail_partition field to support Capital One's MAAS (Marketing as a Service) program, which requires separating mail into batches by pop_id for per-dealership USPS postage statements.

• Adds mail_partition field definition to all letter schemas (request and response models)
• Includes example values in request and response documentation
• Documents the feature flag requirement and account restrictions

Reviewed changes

Copilot reviewed 9 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
shared/attributes/mail_partition.yml	Defines the mail_partition attribute schema with description, type, and nullable flag
resources/letters/models/letter_editable.yml	Adds mail_partition to the letter request schema
resources/letters/models/no_extra_service.yml	Adds mail_partition to the no_extra_service letter response model
resources/letters/models/registered.yml	Adds mail_partition to the registered letter response model
resources/letters/models/certified.yml	Adds mail_partition to the certified letter response model
resources/letters/letters.yml	Adds mail_partition examples (1076, 1122) to JSON and form-urlencoded request bodies
resources/letters/responses/letter.yml	Adds mail_partition: "1076" to single letter response example
resources/letters/responses/all_letters.yml	Adds mail_partition: "1076" to list response example
lob-api-public.yml	Documents the Mail Partitioning and Batching feature, feature flag requirement, and version bump to 1.20.9
dist/lob-api-bundled.yml	Reflects all changes in the bundled OpenAPI specification with proper schema definitions and examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.