{ "openapi": "3.1.0", "info": { "title": "ShiftForest account email API", "version": "1.0.0", "description": "Human account endpoints; integration API keys are not accepted. Platform campaign access requires existing superadmin privileges and TOTP MFA within 10 minutes. Optional sending defaults off pending provider commissioning. Global caps: one reservation/24 hours, two/7 days, two inactivity/90 days; quiet hours use IANA timezone. All responses are no-store. No reading/open tracking. Provider acceptance is not inbox delivery. Public unsubscribe is available at the app host; campaign/prefs APIs at both hosts." }, "servers": [ { "url": "https://app.shiftforest.com" }, { "url": "https://api.shiftforest.com" } ], "components": { "securitySchemes": { "HumanSession": { "type": "http", "scheme": "bearer", "bearerFormat": "Supabase JWT" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Topics": { "type": "object", "additionalProperties": false, "properties": { "getting_started": { "type": "boolean" }, "inactivity": { "type": "boolean" }, "product_updates": { "type": "boolean" }, "offers": { "type": "boolean" } }, "required": [ "getting_started", "inactivity", "product_updates", "offers" ] }, "Preferences": { "type": "object", "required": [ "revision", "topics", "notice_version", "timezone", "quiet_start", "quiet_end", "eligible", "verified", "suppressed" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "topics": { "$ref": "#/components/schemas/Topics" }, "notice_version": { "type": "string" }, "timezone": { "type": "string" }, "quiet_start": { "type": "integer", "minimum": 0, "maximum": 23 }, "quiet_end": { "type": "integer", "minimum": 0, "maximum": 23 }, "eligible": { "type": "boolean" }, "verified": { "type": "boolean" }, "suppressed": { "type": "boolean" } } }, "PreferenceChanges": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "topics": { "type": "object", "additionalProperties": false, "properties": { "getting_started": { "type": "boolean" }, "inactivity": { "type": "boolean" }, "product_updates": { "type": "boolean" }, "offers": { "type": "boolean" } }, "minProperties": 1 }, "notice_version": { "type": "string", "enum": [ "2026-10-30" ] }, "timezone": { "type": "string" }, "quiet_start": { "type": "integer", "minimum": 0, "maximum": 23 }, "quiet_end": { "type": "integer", "minimum": 0, "maximum": 23 } } }, "CampaignContent": { "type": "object", "required": [ "topic", "subject", "paragraphs", "action" ], "additionalProperties": false, "properties": { "topic": { "type": "string", "enum": [ "product_updates", "offers" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 100 }, "paragraphs": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "string", "minLength": 1, "maxLength": 900 } }, "action": { "type": "object", "required": [ "label", "url" ], "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "url": { "type": "string", "enum": [ "https://app.shiftforest.com/", "https://app.shiftforest.com/pricing", "https://app.shiftforest.com/developers", "https://app.shiftforest.com/onboarding" ] } } } } }, "Campaign": { "type": "object", "required": [ "id", "revision", "state", "content", "content_hash" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "state": { "type": "string", "enum": [ "draft", "approved", "scheduled", "paused", "cancelled" ] }, "content": { "$ref": "#/components/schemas/CampaignContent" }, "content_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "eligible_now_estimate": { "type": "integer" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "counts": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } } } } } }, "paths": { "/api/email/preferences": { "get": { "operationId": "getEmailPreferences", "summary": "Read your own account preferences; defaults off and address changes clear opt-ins.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preferences" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "saveEmailPreferences", "summary": "Save explicit choices. Opt-in requires verified owner/admin and current notice version.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preferences" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "Quoted revision from the latest representation, e.g. \"2\".", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,14}\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceChanges" } } } } } }, "/api/email/activity": { "post": { "operationId": "recordEmailForegroundActivity", "summary": "Coarse 30-minute watermark for real foreground interaction, not background or employee activity.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/email/export": { "get": { "operationId": "exportOwnEmailData", "summary": "Export your own preferences, consent history and recent delivery states.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences", "consent_history", "recent_deliveries" ], "properties": { "preferences": { "$ref": "#/components/schemas/Preferences" }, "consent_history": { "type": "array", "items": { "type": "object" } }, "recent_deliveries": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/email/campaigns": { "get": { "operationId": "listEmailCampaigns", "summary": "Platform operator and recent MFA only. Newest first; up to 100 records.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "limit": { "type": "integer" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "next_cursor from the previous page; excludes records at or newer than that boundary." } ] }, "post": { "operationId": "createEmailCampaign", "summary": "Create a draft; same UUID/content is replay-safe, conflicting reuse is rejected.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "content" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "$ref": "#/components/schemas/CampaignContent" } } } } } } } }, "/api/email/campaigns/{id}": { "get": { "operationId": "getEmailCampaign", "summary": "Get campaign and aggregate counts; recent MFA required.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "operationId": "editEmailCampaign", "summary": "Edit draft only; approved content is immutable.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted revision from the latest representation, e.g. \"2\".", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,14}\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "additionalProperties": false, "properties": { "content": { "$ref": "#/components/schemas/CampaignContent" } } } } } } } }, "/api/email/campaigns/{id}/review": { "get": { "operationId": "reviewEmailCampaign", "summary": "Review exact copy and hash with current estimated eligibility; not a delivery guarantee.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/email/campaigns/{id}/approve": { "post": { "operationId": "approveEmailCampaign", "summary": "Platform operator and recent MFA; state transition with current revision. Scheduling accepts UTC within 90 days, expires after 48 hours.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted revision from the latest representation, e.g. \"2\".", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,14}\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "content_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "content_hash" ] } } } } } }, "/api/email/campaigns/{id}/schedule": { "post": { "operationId": "scheduleEmailCampaign", "summary": "Platform operator and recent MFA; state transition with current revision. Scheduling accepts UTC within 90 days, expires after 48 hours.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted revision from the latest representation, e.g. \"2\".", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,14}\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "scheduled_at" ] } } } } } }, "/api/email/campaigns/{id}/pause": { "post": { "operationId": "pauseEmailCampaign", "summary": "Platform operator and recent MFA; state transition with current revision. Scheduling accepts UTC within 90 days, expires after 48 hours.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted revision from the latest representation, e.g. \"2\".", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,14}\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/api/email/campaigns/{id}/cancel": { "post": { "operationId": "cancelEmailCampaign", "summary": "Platform operator and recent MFA; state transition with current revision. Scheduling accepts UTC within 90 days, expires after 48 hours.", "security": [ { "HumanSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Human login required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current account permission or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale revision: reload before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match revision required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted revision from the latest representation, e.g. \"2\".", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,14}\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/email/unsubscribe": { "get": { "operationId": "getEmailUnsubscribe", "summary": "Confirmation page without mutation", "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Confirmation HTML" }, "400": { "description": "Malformed capability" }, "503": { "description": "Not committed; retry later" } } }, "post": { "operationId": "postEmailUnsubscribe", "summary": "RFC8058 one-click opt-out: no login, cookies or confirmation; repeated or unknown valid-format token gets generic success.", "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Opt-out committed; generic JSON" }, "400": { "description": "Malformed capability" }, "503": { "description": "Not committed; retry later" } } } } } }