{ "openapi": "3.1.0", "info": { "title": "Mailprompt API", "version": "1.0.0", "description": "The Mailprompt public API (`/v1`). Server-to-server only: send\n`Authorization: Bearer mp_live_...` (or `mp_test_...`). There is no CORS.\n\nConventions: snake_case JSON, ISO-8601 timestamps, opaque cursors\n(`limit` default 50, max 500), `Idempotency-Key` on writes, and the error\nenvelope `{ error: { code, message, request_id } }`. Contract documents\n(`definition`, `ab_config`, `properties`) pass through with the camelCase\nkeys defined by `@mailprompt/contracts`.\n\nThe API can create drafts and request approvals. It never sends email and\nnever makes a flow or campaign live; a human approves and activates in the\napp.\n" }, "servers": [ { "url": "https://api.mailprompt.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Profiles" }, { "name": "Events" }, { "name": "Lists" }, { "name": "Segments" }, { "name": "Flows" }, { "name": "Campaigns" }, { "name": "Results" }, { "name": "Account" }, { "name": "Webhooks" } ], "x-common-headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "paths": { "/v1/profiles": { "get": { "operationId": "listProfiles", "tags": [ "Profiles" ], "summary": "List profiles", "description": "Cursor-paginated, newest id first. Scoped to the key's account.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of profiles.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "post": { "operationId": "upsertProfile", "tags": [ "Profiles" ], "summary": "Create or update a profile by email", "description": "Upserts on the normalised email. `properties` is shallow-merged into the\nexisting record. A suppressed profile cannot be resubscribed through the\nAPI (`409 conflict`). Returns 201 when created, 200 when updated. In\ntest mode the response is synthetic and nothing is persisted.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpsertRequest" } } } }, "responses": { "200": { "description": "The profile was updated.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "201": { "description": "The profile was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/profiles/{id}": { "get": { "operationId": "getProfile", "tags": [ "Profiles" ], "summary": "Get a profile", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The profile.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/events": { "post": { "operationId": "trackEvents", "tags": [ "Events" ], "summary": "Track one event or a batch of up to 100", "description": "`events:write` uses its own rate-limit bucket at 10× the plan rate.\nEvents with a `unique_id` are idempotent per `(account, metric,\nunique_id)`; duplicates are reported, not re-inserted. In test mode the\nresponse is synthetic and no events are stored.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsRequest" } } } }, "responses": { "202": { "description": "Events accepted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/lists": { "get": { "operationId": "listLists", "tags": [ "Lists" ], "summary": "List contact lists", "description": "Cursor-paginated, newest id first. Includes archived lists so callers can audit them.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of lists.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "post": { "operationId": "createList", "tags": [ "Lists" ], "summary": "Create a contact list", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateListRequest" } } } }, "responses": { "201": { "description": "The created list.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/lists/{id}": { "get": { "operationId": "getList", "tags": [ "Lists" ], "summary": "Get a list with member and consent counts", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The list.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "patch": { "operationId": "updateList", "tags": [ "Lists" ], "summary": "Rename a list or change its consent mode", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListRequest" } } } }, "responses": { "200": { "description": "The updated list.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "delete": { "operationId": "archiveList", "tags": [ "Lists" ], "summary": "Archive a list", "description": "Archived lists keep their members and evidence but are hidden from campaign pickers.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "List archived.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/lists/{id}/members": { "get": { "operationId": "listListMembers", "tags": [ "Lists" ], "summary": "List the people on a list", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of members with their consent evidence.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "post": { "operationId": "addListMembers", "tags": [ "Lists" ], "summary": "Add profiles to a list", "description": "All profile ids must belong to the key's account; otherwise 404. At most\n1,000 ids per request. Test mode persists nothing.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMembersRequest" } } } }, "responses": { "201": { "description": "Members added (duplicates counted in `already_members`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMembersResponse" } } } }, "202": { "description": "At or above 1,000 people the addition waits for human approval; nothing was added.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMembersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/lists/{id}/members/{profileId}": { "delete": { "operationId": "removeListMember", "tags": [ "Lists" ], "summary": "Remove a profile from a list", "description": "204 on success, 404 when the list or membership does not exist.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/ProfileId" } ], "responses": { "204": { "description": "Member removed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/segments": { "post": { "operationId": "createSegment", "tags": [ "Segments" ], "summary": "Create a draft segment", "description": "The definition is validated against this account's real lists, tags, metrics, properties, products, collections and segments. Costs 1 credit and emails nobody.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentRequest" } } } }, "responses": { "201": { "description": "The created segment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "get": { "operationId": "listSegments", "tags": [ "Segments" ], "summary": "List segments with their cached counts", "description": "Counts are the cached values written by the segment evaluator\n(`counted_at` says when). Live evaluation is not performed on this path.\n", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of segments.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/segments/preview": { "post": { "operationId": "previewSegment", "tags": [ "Segments" ], "summary": "Validate and count a segment definition", "description": "Uses a 5 second statement timeout and returns `slow: true` instead of hanging. Free.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewSegmentRequest" } } } }, "responses": { "200": { "description": "Validation result, count, summary and masked sample.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewSegmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/segments/{id}": { "get": { "operationId": "getSegment", "tags": [ "Segments" ], "summary": "Get a segment", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The segment with its definition and summary.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "patch": { "operationId": "updateSegment", "tags": [ "Segments" ], "summary": "Save a new segment version", "description": "If a live flow or scheduled campaign uses the segment, the change returns `approval_required: true` and is not applied until an owner approves it. Costs 1 credit.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentRequest" } } } }, "responses": { "200": { "description": "The updated segment, or the pending approval.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/segments/{id}/members": { "get": { "operationId": "listSegmentMembers", "tags": [ "Segments" ], "summary": "Page the people currently in a segment", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of matching profiles.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/segments/{id}/count": { "get": { "operationId": "getSegmentCount", "tags": [ "Segments" ], "summary": "Cached profile count for a segment", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The cached count.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentCount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/flows": { "get": { "operationId": "listFlows", "tags": [ "Flows" ], "summary": "List flows", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of flows.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "post": { "operationId": "createFlowDraft", "tags": [ "Flows" ], "summary": "Create a flow draft", "description": "Creates a `draft` only. Costs 10 credits (PLAN §2); `?dry_run=true`\nreturns `{ dry_run: true, credits: 10 }` and changes nothing. Asking for\n`status: live` is refused with `409 approval_required`: create the draft,\nrequest approval, and let a human activate it. Document, segment and list\nids referenced by the definition must belong to the key's account (404).\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/DryRun" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFlowRequest" } } } }, "responses": { "200": { "description": "Dry run result (`?dry_run=true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "The draft flow.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/flows/{id}": { "get": { "operationId": "getFlow", "tags": [ "Flows" ], "summary": "Get a flow with its definition", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The flow.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/flows/{id}/request-approval": { "post": { "operationId": "requestFlowApproval", "tags": [ "Flows" ], "summary": "Request a human go-live approval for a draft flow", "description": "Creates a pending `Approval` (`kind: flow_live`) through the core\napproval constructor and returns 202. The target id is\n`{flowId}@v{version}` and the snapshot hash covers the whole definition,\nexactly what the engine's `goLiveFlow()` checks. Repeating the call with\nunchanged content returns the pending approval; an expired row is marked\n`expired` and a fresh one is created. The API never flips a flow live.\nCore runs the pre-send checklist on every referenced email first; a\nfailing check returns 422 with the failures in `error.details.checks`.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The pending approval.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ApprovalChecksFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/campaigns": { "get": { "operationId": "listCampaigns", "tags": [ "Campaigns" ], "summary": "List campaigns", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of campaigns.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "post": { "operationId": "createCampaignDraft", "tags": [ "Campaigns" ], "summary": "Create a campaign draft", "description": "Creates a `draft` only. Costs 5 credits; `?dry_run=true` returns the cost\nand changes nothing. `schedule_at` is refused with `409 approval_required`:\ncreate the draft, request approval, and let a human schedule/send it.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/DryRun" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } } }, "responses": { "200": { "description": "Dry run result (`?dry_run=true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "The draft campaign.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/campaigns/{id}/request-approval": { "post": { "operationId": "requestCampaignApproval", "tags": [ "Campaigns" ], "summary": "Request a human send approval for a draft campaign", "description": "Creates a pending `Approval` (`kind: campaign_send`) through\n`requestCampaignApproval` and returns 202. The snapshot hash covers the\ncampaign content config plus the segment definition, exactly what\n`scheduleCampaign()` checks. Expired or stale rows are ignored. Core\nruns the pre-send checklist first; a failing check returns 422 with the\nfailures in `error.details.checks`. The API never sends email.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The pending approval.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ApprovalChecksFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/results/summary": { "get": { "operationId": "getResultsSummary", "tags": [ "Results" ], "summary": "Revenue, sends, opens, clicks and bounces for a date range", "description": "Defaults to the last 30 days. The range is capped at 366 days. Heavy\nendpoint: consumes 5 rate-limit tokens. Uses click-based attribution\n(opens are reported but never used for revenue).\n", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "The summary.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "The key's account, plan and API allowance", "responses": { "200": { "description": "The account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/credits": { "get": { "operationId": "getCredits", "tags": [ "Account" ], "summary": "The account's credit balance", "responses": { "200": { "description": "The balance.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Every endpoint registered for the key's account. Reads use the\n`webhooks:read` scope. Signing secrets are never returned; they are\nshown once at creation or rotation.\n", "responses": { "200": { "description": "The account's endpoints.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Register a webhook endpoint", "description": "The URL must be https, have no embedded credentials and resolve only to\npublic addresses (the SSRF check runs again on every delivery). Events\ncome from the fixed catalogue. An account can have at most 20\nendpoints. The response includes the signing secret exactly once;\nstore it before leaving the page. Requires `webhooks:write`.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } }, "responses": { "201": { "description": "Created. `secret` is shown only in this response.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "Change the URL (re-checked with the https + SSRF guard), the subscribed\nevents or whether the endpoint is enabled. Re-enabling clears the\nfailure streak. Requires `webhooks:write`.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" } } } }, "responses": { "200": { "description": "The updated endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Stops future deliveries and removes the endpoint's delivery log. Requires `webhooks:write`.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Rotate a webhook signing secret", "description": "Replaces the secret and returns the new value exactly once. Deliveries\nalready queued with the old secret will fail verification; update the\nreceiver promptly. Requires `webhooks:write`.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The new secret and the updated endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List the last 30 days of deliveries for an endpoint", "description": "Cursor-paginated, newest first. Each row reports the event, status,\nHTTP status, attempt number, duration and time. Rows older than 30 days\nare purged. Requires `webhooks:read`.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of deliveries.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Queue a signed webhook.test event", "description": "Queues one `webhook.test` delivery for this endpoint. It is signed with\nthe endpoint secret and sent by the delivery worker like any other\nevent; `webhook.test` is not subscribable. Requires `webhooks:write`.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The test event is queued.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/webhooks/deliveries/{id}/redeliver": { "post": { "operationId": "redeliverWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Redeliver a logged delivery", "description": "Re-queues the same event with the same event id and payload, so a\nreceiver can deduplicate it against the original. The retry count\nstarts again. Requires `webhooks:write`.\n", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The delivery is queued again.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "mp_live_<8>_<32> | mp_test_<8>_<32>", "description": "API key as `Authorization: Bearer `. Keys in a query string are\nrejected with `400 key_in_query`.\n" } }, "headers": { "X-Request-Id": { "description": "Unique id for this request; quote it in support requests.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests per minute allowed for this key/bucket.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Tokens left in the bucket.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the bucket refills.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (429 and retryable 409 responses).", "schema": { "type": "integer" } }, "X-Mailprompt-Test-Mode": { "description": "Present with value `true` on every response to an `mp_test_` key.", "schema": { "type": "string", "enum": [ "true" ] } } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, "ProfileId": { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque `next_cursor` from the previous page.", "schema": { "type": "string", "maxLength": 512 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 100 characters. The first response is stored for 24 hours and\nreplayed for the same method, path and body; a different body returns\n`409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, "DryRun": { "name": "dry_run", "in": "query", "required": false, "description": "On a billable write, return the credit cost and change nothing.", "schema": { "type": "boolean", "default": false } } }, "responses": { "BadRequest": { "description": "Malformed request, invalid cursor, oversized body or an API key passed in the query string.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Missing, malformed, unknown, revoked or expired API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PaymentRequired": { "description": "Not enough credits for this billable write.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Missing scope, IP not allowed, unknown/read-only plan.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "The resource does not exist in this account (cross-store ids are 404).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Conflict": { "description": "State conflict, concurrent idempotent request, or an approval is required / already granted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ValidationFailed": { "description": "Zod validation failed; `error.fields` maps field paths to messages.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ApprovalChecksFailed": { "description": "The pre-send checklist (PLAN §9 #12) blocked the approval request.\n`error.code` is `validation_failed`; `error.details.checks` lists each\ndocument it rendered and the failing checks, so a client can show the\nhuman exactly what to fix. A missing brand kit is reported the same\nway; a missing or invalid referenced document also returns\n`422 validation_failed`.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate limit or monthly quota exceeded; see `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Internal": { "description": "Unexpected error. No stack traces or internal messages are returned.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Mailprompt-Test-Mode": { "$ref": "#/components/headers/X-Mailprompt-Test-Mode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "key_in_query", "unauthorized", "forbidden", "not_found", "conflict", "idempotency_mismatch", "validation_failed", "payment_required", "approval_required", "rate_limited", "quota_exceeded", "internal" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "details": { "type": "object", "additionalProperties": true, "description": "Structured context for the failure. On a 422 from\n`request-approval`, `details.checks` is an array of\n`{ document_id, checks: [{ id, severity, passed, message }] }`.\n" } } } } }, "ProfileUpsertRequest": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 32 }, "properties": { "type": "object", "additionalProperties": true }, "consent_status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "pending", "never_subscribed" ] }, "consent_source": { "type": "string", "maxLength": 200 } } }, "Profile": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "email", "first_name", "last_name", "phone", "properties", "consent_status", "consent_source", "consent_at", "suppressed", "suppressed_reason", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "profile" ] }, "email": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "properties": { "type": "object", "additionalProperties": true }, "consent_status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "pending", "never_subscribed" ] }, "consent_source": { "type": [ "string", "null" ] }, "consent_at": { "type": [ "string", "null" ], "format": "date-time" }, "suppressed": { "type": "boolean" }, "suppressed_reason": { "type": [ "string", "null" ], "enum": [ "hard_bounce", "complaint", "manual", "invalid", "global", null ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProfileList": { "type": "object", "additionalProperties": false, "required": [ "profiles", "next_cursor" ], "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "EventInput": { "type": "object", "additionalProperties": false, "required": [ "metric" ], "properties": { "metric": { "type": "string", "minLength": 1, "maxLength": 64 }, "profile_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "properties": { "type": "object", "additionalProperties": true }, "value": { "type": "integer" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "occurred_at": { "type": "string", "format": "date-time" }, "unique_id": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "EventsRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "event" ], "properties": { "event": { "$ref": "#/components/schemas/EventInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/EventInput" } } } } ] }, "EventsResponse": { "type": "object", "additionalProperties": false, "required": [ "accepted", "duplicates", "results" ], "properties": { "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "index", "event_id", "status" ], "properties": { "index": { "type": "integer" }, "event_id": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "duplicate" ] } } } } } }, "AddMembersRequest": { "type": "object", "additionalProperties": false, "required": [ "profile_ids" ], "properties": { "profile_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "source": { "type": "string", "minLength": 1, "maxLength": 120 }, "consent_evidence": { "oneOf": [ { "$ref": "#/components/schemas/ConsentEvidence" }, { "type": "null" } ] } } }, "ConsentEvidence": { "type": "object", "additionalProperties": false, "required": [ "source" ], "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 200 }, "consented": { "type": "boolean" }, "textShown": { "type": "string", "maxLength": 2000 }, "ip": { "type": "string", "maxLength": 64 }, "formId": { "type": "string", "maxLength": 80 }, "importId": { "type": "string", "maxLength": 80 }, "at": { "type": "integer", "minimum": 0 } } }, "ListMembersResponse": { "type": "object", "additionalProperties": false, "required": [ "list_id", "added", "already_members", "member_count", "subscribed", "not_consented", "approval_required", "approval_id" ], "properties": { "list_id": { "type": "string" }, "added": { "type": "integer" }, "already_members": { "type": "integer" }, "member_count": { "type": "integer" }, "subscribed": { "type": "integer" }, "not_consented": { "type": "integer" }, "approval_required": { "type": "boolean" }, "approval_id": { "type": [ "string", "null" ] } } }, "List": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "description", "consent_mode", "kind", "archived_at", "members", "subscribed", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "list" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "consent_mode": { "type": "string", "enum": [ "single_opt_in", "double_opt_in" ] }, "kind": { "type": "string", "enum": [ "standard", "imported", "form", "store" ] }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "members": { "type": "integer" }, "subscribed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ListList": { "type": "object", "additionalProperties": false, "required": [ "lists", "next_cursor" ], "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/List" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ListResponse": { "type": "object", "additionalProperties": false, "required": [ "list" ], "properties": { "list": { "$ref": "#/components/schemas/List" } } }, "CreateListRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "consent_mode": { "type": "string", "enum": [ "single_opt_in", "double_opt_in" ] }, "kind": { "type": "string", "enum": [ "standard", "imported", "form", "store" ] } } }, "UpdateListRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "consent_mode": { "type": "string", "enum": [ "single_opt_in", "double_opt_in" ] } } }, "ListMemberPage": { "type": "object", "additionalProperties": false, "required": [ "members", "next_cursor" ], "properties": { "members": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "first_name", "last_name", "consent_status", "source", "consent_evidence", "subscribed_at" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "pending", "never_subscribed" ] }, "source": { "type": [ "string", "null" ] }, "consent_evidence": {}, "subscribed_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Segment": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "description", "definition", "summary", "status", "version", "last_error", "count", "counted_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "segment" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "definition": {}, "summary": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "version": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "counted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateSegmentRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "definition" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "definition": {} } }, "UpdateSegmentRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "definition": {} } }, "PreviewSegmentRequest": { "type": "object", "additionalProperties": false, "properties": { "segment_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "definition": {} } }, "PreviewSegmentResponse": { "type": "object", "additionalProperties": false, "required": [ "valid", "errors", "count", "slow", "sample", "summary" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "count": { "type": [ "integer", "null" ] }, "slow": { "type": "boolean" }, "sample": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/SegmentMemberProfile" } }, "summary": { "type": [ "string", "null" ] } } }, "SegmentResponse": { "type": "object", "additionalProperties": false, "required": [ "segment" ], "properties": { "segment": { "$ref": "#/components/schemas/Segment" }, "approval_required": { "type": "boolean" }, "approval_id": { "type": [ "string", "null" ] } } }, "SegmentMemberProfile": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "email", "first_name", "last_name", "consent_status", "last_order_at", "total_spent_minor" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "profile" ] }, "email": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "pending", "never_subscribed" ] }, "last_order_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_spent_minor": { "type": "integer" } } }, "SegmentMemberPage": { "type": "object", "additionalProperties": false, "required": [ "profiles", "next_cursor" ], "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentMemberProfile" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "SegmentList": { "type": "object", "additionalProperties": false, "required": [ "segments", "next_cursor" ], "properties": { "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "SegmentCount": { "type": "object", "additionalProperties": false, "required": [ "segment_id", "count", "counted_at", "cached" ], "properties": { "segment_id": { "type": "string" }, "count": { "type": "integer" }, "counted_at": { "type": [ "string", "null" ], "format": "date-time" }, "cached": { "type": "boolean" } } }, "MetricTrigger": { "type": "object", "additionalProperties": false, "required": [ "metric" ], "properties": { "metric": { "type": "string", "minLength": 1, "maxLength": 64 }, "where": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } }, "FixedDateSpec": { "type": "object", "additionalProperties": false, "required": [ "month", "day", "leadDays" ], "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 }, "leadDays": { "type": "integer", "minimum": 0, "maximum": 365 } } }, "NthWeekdayDateSpec": { "type": "object", "additionalProperties": false, "required": [ "month", "weekday", "nth", "leadDays" ], "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6 }, "nth": { "type": "integer", "minimum": 1, "maximum": 5 }, "leadDays": { "type": "integer", "minimum": 0, "maximum": 365 } } }, "DateTrigger": { "type": "object", "additionalProperties": false, "required": [ "date" ], "properties": { "date": { "oneOf": [ { "$ref": "#/components/schemas/FixedDateSpec" }, { "$ref": "#/components/schemas/NthWeekdayDateSpec" } ] } } }, "PropertyDateTrigger": { "type": "object", "additionalProperties": false, "required": [ "property", "leadDays" ], "properties": { "property": { "type": "string", "minLength": 1, "maxLength": 100 }, "leadDays": { "type": "integer", "minimum": 0, "maximum": 365 } } }, "SegmentEntryTrigger": { "type": "object", "additionalProperties": false, "required": [ "segmentId" ], "properties": { "segmentId": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "FlowTrigger": { "oneOf": [ { "$ref": "#/components/schemas/MetricTrigger" }, { "$ref": "#/components/schemas/DateTrigger" }, { "$ref": "#/components/schemas/PropertyDateTrigger" }, { "$ref": "#/components/schemas/SegmentEntryTrigger" } ] }, "FlowAudience": { "oneOf": [ { "type": "string", "enum": [ "any", "subscribed" ] }, { "type": "object", "additionalProperties": false, "required": [ "list" ], "properties": { "list": { "type": "string", "minLength": 1, "maxLength": 80 } } }, { "type": "object", "additionalProperties": false, "required": [ "segmentId" ], "properties": { "segmentId": { "type": "string", "minLength": 1, "maxLength": 80 } } } ] }, "FlowEventRule": { "type": "object", "additionalProperties": false, "required": [ "metric", "since" ], "properties": { "metric": { "type": "string", "minLength": 1, "maxLength": 64 }, "since": { "type": "string", "enum": [ "trigger" ] } } }, "QuietHours": { "type": "object", "additionalProperties": false, "required": [ "start", "end" ], "properties": { "start": { "type": "integer", "minimum": 0, "maximum": 23 }, "end": { "type": "integer", "minimum": 0, "maximum": 23 } } }, "FlowSendVariant": { "type": "object", "additionalProperties": false, "required": [ "weight", "subject", "documentId" ], "properties": { "weight": { "type": "integer", "minimum": 0, "maximum": 100 }, "subject": { "type": "string", "minLength": 1, "maxLength": 150 }, "documentId": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "FlowSendSpec": { "type": "object", "additionalProperties": false, "required": [ "documentId", "subject", "marketing" ], "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 80 }, "subject": { "type": "string", "minLength": 1, "maxLength": 150 }, "preheader": { "type": "string", "maxLength": 150 }, "marketing": { "type": "boolean" }, "couponRuleId": { "type": "string", "minLength": 1, "maxLength": 80 }, "variants": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/FlowSendVariant" } } } }, "FlowWaitStep": { "type": "object", "additionalProperties": false, "required": [ "wait" ], "properties": { "wait": { "type": "string", "pattern": "^[0-9]{1,6}[mhdw]$" } } }, "FlowSendStep": { "type": "object", "additionalProperties": false, "required": [ "send" ], "properties": { "send": { "$ref": "#/components/schemas/FlowSendSpec" } } }, "FlowIfCondition": { "type": "object", "additionalProperties": false, "properties": { "noEvent": { "oneOf": [ { "$ref": "#/components/schemas/FlowEventRule" }, { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/FlowEventRule" } } ] }, "inSegment": { "type": "string", "minLength": 1, "maxLength": 80 }, "property": { "type": "object", "additionalProperties": false, "required": [ "name", "eq" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "eq": { "type": [ "string", "number", "boolean" ] } } } } }, "FlowIfStep": { "type": "object", "additionalProperties": false, "required": [ "if", "then" ], "properties": { "if": { "$ref": "#/components/schemas/FlowIfCondition" }, "then": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FlowStep" } }, "else": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FlowStep" } } } }, "FlowStep": { "oneOf": [ { "$ref": "#/components/schemas/FlowWaitStep" }, { "$ref": "#/components/schemas/FlowSendStep" }, { "$ref": "#/components/schemas/FlowIfStep" } ] }, "FlowDefinition": { "description": "The engine's stored flow definition. `id`, `accountId` and `name` are\nadded by the API from the create request; clients do not send them.\n", "type": "object", "additionalProperties": false, "required": [ "id", "accountId", "name", "trigger", "audience", "steps" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "accountId": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "trigger": { "$ref": "#/components/schemas/FlowTrigger" }, "audience": { "$ref": "#/components/schemas/FlowAudience" }, "reentryDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "exitOn": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FlowEventRule" } }, "quietHours": { "$ref": "#/components/schemas/QuietHours" }, "steps": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/FlowStep" } } } }, "FlowDefinitionInput": { "description": "The trigger/audience/steps a client sends; the API adds the identity fields.", "type": "object", "additionalProperties": false, "required": [ "trigger", "audience", "steps" ], "properties": { "trigger": { "$ref": "#/components/schemas/FlowTrigger" }, "audience": { "$ref": "#/components/schemas/FlowAudience" }, "reentryDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "exitOn": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FlowEventRule" } }, "quietHours": { "$ref": "#/components/schemas/QuietHours" }, "steps": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/FlowStep" } } } }, "CreateFlowRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "definition" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "definition": { "$ref": "#/components/schemas/FlowDefinitionInput" }, "status": { "type": "string", "enum": [ "draft", "live" ], "default": "draft" } } }, "FlowSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "status", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "flow" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "live", "paused", "archived" ] }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Flow": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "status", "version", "definition", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "flow" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "live", "paused", "archived" ] }, "version": { "type": "integer" }, "definition": { "$ref": "#/components/schemas/FlowDefinition" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FlowList": { "type": "object", "additionalProperties": false, "required": [ "flows", "next_cursor" ], "properties": { "flows": { "type": "array", "items": { "$ref": "#/components/schemas/FlowSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CampaignVariant": { "type": "object", "additionalProperties": false, "required": [ "key", "subject", "document_id" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 40 }, "subject": { "type": "string", "minLength": 1, "maxLength": 150 }, "document_id": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "CreateCampaignRequest": { "description": "`document_id` is required to create a campaign; it is optional in the\nschema only so `?dry_run=true` needs nothing but a name. The content\nfields are persisted so the core `campaign_snapshot` can hash them.\n", "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "document_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "subject": { "type": "string", "minLength": 1, "maxLength": 150 }, "segment_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "preheader": { "type": "string", "maxLength": 150 }, "marketing": { "type": "boolean", "description": "Defaults to true." }, "coupon_rule_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "variants": { "type": "array", "minItems": 2, "maxItems": 3, "items": { "$ref": "#/components/schemas/CampaignVariant" } }, "test_percent": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Defaults to 20." }, "decide_after_minutes": { "type": "integer", "minimum": 5, "maximum": 10080, "description": "Defaults to 240." }, "schedule_at": { "type": "string", "format": "date-time" } } }, "Campaign": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "status", "segment_id", "document_id", "subject", "scheduled_at", "ab_config", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "campaign" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "sent", "cancelled" ] }, "segment_id": { "type": [ "string", "null" ] }, "document_id": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "ab_config": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CampaignList": { "type": "object", "additionalProperties": false, "required": [ "campaigns", "next_cursor" ], "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Approval": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "kind", "target_id", "status", "requested_by", "note", "expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "approval" ] }, "kind": { "type": "string", "description": "Every approval kind the product creates (`ApprovalKind` in the\ndatabase schema). `large_segment_send` is retired: `campaign_send`\nis the single large-audience gate.\n", "enum": [ "flow_live", "flow_change", "campaign_send", "import", "segment_change", "list_add", "form_publish" ] }, "target_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "requested_by": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ResultsSummary": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "currency", "emails_sent", "opens", "clicks", "bounces", "revenue_minor", "attributed_orders", "attributed_revenue_minor", "per_flow", "per_campaign" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "emails_sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "bounces": { "type": "integer" }, "revenue_minor": { "type": "integer" }, "attributed_orders": { "type": "integer" }, "attributed_revenue_minor": { "type": "integer" }, "per_flow": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "flow_id", "name", "emails_sent", "revenue_minor" ], "properties": { "flow_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "emails_sent": { "type": "integer" }, "revenue_minor": { "type": "integer" } } } }, "per_campaign": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "campaign_id", "name", "emails_sent", "revenue_minor" ], "properties": { "campaign_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "emails_sent": { "type": "integer" }, "revenue_minor": { "type": "integer" } } } } } }, "WebhookEventType": { "type": "string", "enum": [ "profile.subscribed", "profile.unsubscribed", "message.sent", "message.bounced", "message.complained", "message.clicked", "order.attributed", "flow.approved", "campaign.sent", "approval.requested", "credits.low" ] }, "Webhook": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "url", "description", "events", "enabled", "last_delivery_at", "consecutive_failures", "disabled_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "enabled": { "type": "boolean" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "type": "integer", "minimum": 0 }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookList": { "type": "object", "additionalProperties": false, "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } }, "WebhookResponse": { "type": "object", "additionalProperties": false, "required": [ "webhook" ], "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } } }, "WebhookCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "events": { "type": "array", "minItems": 1, "maxItems": 11, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "description": { "type": [ "string", "null" ], "maxLength": 200 } } }, "WebhookCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "webhook", "secret" ], "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string", "description": "The signing secret. Shown only once; store it securely." } } }, "WebhookUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "events": { "type": "array", "minItems": 1, "maxItems": 11, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "enabled": { "type": "boolean" } } }, "WebhookSecretResponse": { "type": "object", "additionalProperties": false, "required": [ "webhook", "secret" ], "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string", "description": "The new signing secret. Shown only once; store it securely." } } }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "event", "status", "http_status", "attempt", "duration_ms", "error", "at", "delivered_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "event": { "type": "string", "enum": [ "profile.subscribed", "profile.unsubscribed", "message.sent", "message.bounced", "message.complained", "message.clicked", "order.attributed", "flow.approved", "campaign.sent", "approval.requested", "credits.low", "webhook.test" ] }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "http_status": { "type": [ "integer", "null" ] }, "attempt": { "type": "integer", "minimum": 0 }, "duration_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookDeliveryList": { "type": "object", "additionalProperties": false, "required": [ "deliveries", "next_cursor" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "WebhookDeliveryResponse": { "type": "object", "additionalProperties": false, "required": [ "delivery" ], "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "WebhookTestResponse": { "type": "object", "additionalProperties": false, "required": [ "delivery_id", "event_id" ], "properties": { "delivery_id": { "type": "string" }, "event_id": { "type": "string" } } }, "Account": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "store_url", "plan", "timezone", "currency", "rate_limit_per_minute", "api_calls_per_month", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "account" ] }, "name": { "type": "string" }, "store_url": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "rate_limit_per_minute": { "type": [ "integer", "null" ] }, "api_calls_per_month": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Credits": { "type": "object", "additionalProperties": false, "required": [ "account_id", "balance", "currency", "as_of" ], "properties": { "account_id": { "type": "string" }, "balance": { "type": "integer" }, "currency": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } }, "DryRun": { "type": "object", "additionalProperties": false, "required": [ "dry_run", "credits" ], "properties": { "dry_run": { "type": "boolean", "enum": [ true ] }, "credits": { "type": "integer" } } } } } }