docs(api): add POST /member/notify - #395
Merged
Merged
Conversation
Document the endpoint that sends an email notification to account members with a caller-supplied HTML body. Adds the operation to the platform module spec and the merged spec (en/zh), including request and response schemas, per-recipient result reasons, and the shared error responses used by the other /member/* operations. Registers the new page in the API reference navigation alongside its siblings.
The email body is now exactly the sanitized html with no platform layout, sender line, session link, footer, or subject prefix. Attribution moves to the sender display name instead. Inline style attributes are kept as written; the previous CSS property allowlist is removed. Add a dry_run request field: when true, every check runs (validation, sanitize, membership, email, preference, per-turn duplicate, hourly rate) without sending, and the response includes the exact email in a new html field.
The endpoint's gateway route is registered without auditing, so the usage note claiming every call is recorded in the account audit log was incorrect.
The sanitizer removes disallowed content without an error, so a dry run is the only way to see the email recipients will get. Say so in the operation description, which is what generated clients show as the command help.
Recipients in every locale see the caller's name followed by (via AI SRE).
An items array beside scalar fields reads as a list page, and the CLI bounds list pages by withholding rows. A dry run's html sibling made every realistic email overflow that bound. Naming the per-recipient outcomes recipients keeps the response a plain object.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents
POST /member/notify(operationIdmemberNotify, tag Platform / Members) in the en and zh specs,openapi.*.jsonandplatform.openapi.*.json, and adds it to thedocs.jsonnavigation.The endpoint emails account members on the caller's behalf. The message is written by an AI SRE agent inside an AI SRE session; any other credential gets a permission error.
subjectis 1–200 characters, used as written.htmlis an HTML fragment of up to 102,400 bytes and must be non-empty after sanitizing; recipients receive it as the whole email body, with nothing added around it — no platform layout, sender line, session link, footer, or subject prefix. The sender display name carries attribution instead: "<caller name>(via AI SRE)".person_idsis optional, up to 20, and defaults to the caller.dry_run(boolean, defaultfalse) runs every check — validation, sanitize, membership, email, preference, per-turn duplicate, hourly rate — without sending anything.httpsimage sources survive. Links are limited to http, https and mailto. Inlinestyleattributes are kept as written.recipients[]entry per recipient, with statusacceptedorskippedand a reason:not_member,no_email,email_disabled,duplicate,rate_limitedorsend_failed. Withdry_run: true,recipientsreflects what a real send would return, andhtmlcarries the exact, sanitized email document that would have been sent.The outcomes are named
recipients, notitems: across this API anitemsarray next to scalar fields is a list page, and clients that bound list pages (the CLI's structured output does) would withhold outcomes to make room for a largehtml.Checks
jq emptypasses on all four spec files, andpython3 scripts/lint_openapi.pypasses.