{ "openapi": "3.1.0", "info": { "title": "Pidgely API", "version": "1.0.0", "summary": "Multi-tenant e-mail API with its own MTA, compatible with the Resend API.", "description": "Pidgely implements the Resend REST API (same paths, bodies, responses, errors and pagination) so the official Resend SDKs work by changing their base URL, plus a native `/v1` API, a cookie-session dashboard API (`/auth`, `/me`, `/dashboard/*`) and operator endpoints (`/admin/v1`).\n\nErrors on Resend-compatible and dashboard routes have the shape `{\"statusCode\", \"name\", \"message\"}`; native `/v1` and admin routes use `{\"error\": {\"code\", \"message\", \"field\"}}`.\n\nList endpoints use cursor pagination: `limit` (1-100), `after` and `before` take item ids and the response is `{\"object\": \"list\", \"has_more\", \"data\"}`.\n\nCORS preflight (`OPTIONS`) is answered for `/public/*` (`CORS_ORIGINS`) and for `/auth/*`, `/me` and `/dashboard/*` (`DASHBOARD_ORIGINS`, with credentials).", "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.pidgely.com" } ], "tags": [ { "name": "Admin" }, { "name": "API keys" }, { "name": "Audiences (legacy)" }, { "name": "Auth" }, { "name": "Broadcasts" }, { "name": "Contacts" }, { "name": "Dashboard: API keys" }, { "name": "Dashboard: Audiences (legacy)" }, { "name": "Dashboard: Broadcasts" }, { "name": "Dashboard: Contacts" }, { "name": "Dashboard: Domains" }, { "name": "Dashboard: Emails" }, { "name": "Dashboard: Organization" }, { "name": "Dashboard: Segments" }, { "name": "Dashboard: Suppressions" }, { "name": "Dashboard: Team" }, { "name": "Dashboard: Templates" }, { "name": "Dashboard: Webhooks" }, { "name": "Domains" }, { "name": "Emails" }, { "name": "Public" }, { "name": "Operations" }, { "name": "Me" }, { "name": "Segments" }, { "name": "Suppressions" }, { "name": "Templates" }, { "name": "Native API (v1)" }, { "name": "Webhooks" } ], "paths": { "/admin/v1/tenants": { "post": { "tags": [ "Admin" ], "summary": "Create a tenant (with a first API key)", "operationId": "native_post_admin_v1_tenants", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "admin": [] } ] } }, "/admin/v1/tenants/{id}": { "get": { "tags": [ "Admin" ], "summary": "Retrieve a tenant", "operationId": "native_get_admin_v1_tenants_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "admin": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Update a tenant (status, quotas, plan, limits)", "operationId": "native_patch_admin_v1_tenants_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": "string" }, "daily_quota": { "type": "integer" }, "send_rate_per_sec": { "type": "integer" }, "api_rate_per_sec": { "type": "integer" }, "delivery_mode": { "type": "string" }, "plan": { "type": "string" }, "monthly_quota": { "type": "integer" }, "max_domains": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "admin": [] } ] } }, "/admin/v1/waitlist": { "get": { "tags": [ "Admin" ], "summary": "List the waitlist (JSON pages) or export it (?format=csv)", "operationId": "native_get_admin_v1_waitlist", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "object", "has_more", "data" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "admin": [] } ] } }, "/api-keys": { "post": { "tags": [ "API keys" ], "summary": "Create an API key", "operationId": "post_api_keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "domain_id": { "type": "string", "format": "uuid" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "API keys" ], "summary": "List API keys", "operationId": "get_api_keys", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/api-keys/{id}": { "patch": { "tags": [ "API keys" ], "summary": "Rename an API key", "operationId": "patch_api_keys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "API keys" ], "summary": "Revoke an API key", "operationId": "delete_api_keys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/audiences": { "post": { "tags": [ "Audiences (legacy)" ], "summary": "Create a audience", "operationId": "post_audiences", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Audiences (legacy)" ], "summary": "List audiences", "operationId": "get_audiences", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/audiences/{id}": { "get": { "tags": [ "Audiences (legacy)" ], "summary": "Retrieve a audience", "operationId": "get_audiences_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Audiences (legacy)" ], "summary": "Delete a audience", "operationId": "delete_audiences_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/audiences/{id}/contacts": { "get": { "tags": [ "Audiences (legacy)" ], "summary": "List a audience's contacts", "operationId": "get_audiences_id_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "Audiences (legacy)" ], "summary": "Create a contact in an audience", "operationId": "post_audiences_id_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/audiences/{id}/contacts/{key}": { "get": { "tags": [ "Audiences (legacy)" ], "summary": "Retrieve a contact", "operationId": "get_audiences_id_contacts_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Audiences (legacy)" ], "summary": "Update a contact", "operationId": "patch_audiences_id_contacts_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Audiences (legacy)" ], "summary": "Delete a contact", "operationId": "delete_audiences_id_contacts_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "contact": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/auth/invites/accept": { "post": { "tags": [ "Auth" ], "summary": "Accept an invitation (new users choose a password)", "operationId": "post_auth_invites_accept", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" } }, "required": [ "token", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionUser" } } }, "headers": { "Set-Cookie": { "description": "pdg_session=; HttpOnly; SameSite=Lax; Secure", "schema": { "type": "string" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Sign in (rate-limited, lockout after 10 failures)", "operationId": "post_auth_login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionUser" } } }, "headers": { "Set-Cookie": { "description": "pdg_session=; HttpOnly; SameSite=Lax; Secure", "schema": { "type": "string" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Sign out", "operationId": "post_auth_logout", "description": "Requires the dashboard Origin header (CSRF).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/auth/password/forgot": { "post": { "tags": [ "Auth" ], "summary": "E-mail a password reset link (same answer for unknown e-mails)", "operationId": "post_auth_password_forgot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/auth/password/reset": { "post": { "tags": [ "Auth" ], "summary": "Set a new password from a reset link (revokes all sessions)", "operationId": "post_auth_password_reset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "password": { "type": "string" } }, "required": [ "token", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/auth/signup": { "post": { "tags": [ "Auth" ], "summary": "Create a user and organization; sends the verification e-mail", "operationId": "post_auth_signup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string", "minLength": 10, "maxLength": 256 }, "name": { "type": "string" }, "organization": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "pt-br", "es" ] } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "organization": { "$ref": "#/components/schemas/Organization" }, "next": { "type": "string" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/auth/verify": { "post": { "tags": [ "Auth" ], "summary": "Confirm the e-mail address and sign in", "operationId": "post_auth_verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionUser" } } }, "headers": { "Set-Cookie": { "description": "pdg_session=; HttpOnly; SameSite=Lax; Secure", "schema": { "type": "string" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/auth/verify/resend": { "post": { "tags": [ "Auth" ], "summary": "Send a new verification link", "operationId": "post_auth_verify_resend", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/broadcasts": { "post": { "tags": [ "Broadcasts" ], "summary": "Create a broadcast (optionally send)", "operationId": "post_broadcasts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Broadcasts" ], "summary": "List broadcasts", "operationId": "get_broadcasts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/broadcasts/{id}": { "get": { "tags": [ "Broadcasts" ], "summary": "Retrieve a broadcast", "operationId": "get_broadcasts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Broadcasts" ], "summary": "Update a draft broadcast", "operationId": "patch_broadcasts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Broadcasts" ], "summary": "Delete a broadcast", "operationId": "delete_broadcasts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/broadcasts/{id}/cancel": { "post": { "tags": [ "Broadcasts" ], "summary": "Cancel a scheduled or queued broadcast", "operationId": "post_broadcasts_id_cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/broadcasts/{id}/duplicate": { "post": { "tags": [ "Broadcasts" ], "summary": "Duplicate a broadcast as a draft", "operationId": "post_broadcasts_id_duplicate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/broadcasts/{id}/send": { "post": { "tags": [ "Broadcasts" ], "summary": "Send a broadcast now or at scheduled_at", "operationId": "post_broadcasts_id_send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/contacts": { "post": { "tags": [ "Contacts" ], "summary": "Create (or update) a contact", "operationId": "post_contacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Contacts" ], "summary": "List contacts", "operationId": "get_contacts", "parameters": [ { "name": "segment_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "audience_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Legacy alias of segment_id." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Prefix of the e-mail, first or last name (Pidgely extension)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/contacts/batch": { "post": { "tags": [ "Contacts" ], "summary": "Upsert up to 1,000 contacts (Pidgely extension)", "operationId": "post_contacts_batch", "description": "Each row is saved independently; invalid rows are reported in errors with their index.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/ContactInput" } }, "segment_id": { "type": "string", "format": "uuid", "description": "Added to every row." } }, "required": [ "contacts" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBatchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/contacts/{key}": { "get": { "tags": [ "Contacts" ], "summary": "Retrieve a contact", "operationId": "get_contacts_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact (unsubscribed syncs the suppression list)", "operationId": "patch_contacts_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "operationId": "delete_contacts_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "contact": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/contacts/{key}/segments": { "get": { "tags": [ "Contacts" ], "summary": "List a contact's segments", "operationId": "get_contacts_key_segments", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/contacts/{key}/segments/{segment_id}": { "post": { "tags": [ "Contacts" ], "summary": "Add a contact to a segment", "operationId": "post_contacts_key_segments_segment_id", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Segment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Remove a contact from a segment", "operationId": "delete_contacts_key_segments_segment_id", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Segment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "segment_id": { "type": "string", "format": "uuid" }, "audienceId": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/dashboard/api-keys": { "post": { "tags": [ "Dashboard: API keys" ], "summary": "Create an API key", "operationId": "dashboard_post_api_keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "domain_id": { "type": "string", "format": "uuid" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: API keys" ], "summary": "List API keys", "operationId": "dashboard_get_api_keys", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/api-keys/{id}": { "patch": { "tags": [ "Dashboard: API keys" ], "summary": "Rename an API key", "operationId": "dashboard_patch_api_keys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: API keys" ], "summary": "Revoke an API key", "operationId": "dashboard_delete_api_keys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/audiences": { "post": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Create a audience", "operationId": "dashboard_post_audiences", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "List audiences", "operationId": "dashboard_get_audiences", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/audiences/{id}": { "get": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Retrieve a audience", "operationId": "dashboard_get_audiences_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "delete": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Delete a audience", "operationId": "dashboard_delete_audiences_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/audiences/{id}/contacts": { "get": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "List a audience's contacts", "operationId": "dashboard_get_audiences_id_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "post": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Create a contact in an audience", "operationId": "dashboard_post_audiences_id_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/audiences/{id}/contacts/{key}": { "get": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Retrieve a contact", "operationId": "dashboard_get_audiences_id_contacts_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Update a contact", "operationId": "dashboard_patch_audiences_id_contacts_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Audiences (legacy)" ], "summary": "Delete a contact", "operationId": "dashboard_delete_audiences_id_contacts_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "contact": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/broadcasts": { "post": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Create a broadcast (optionally send)", "operationId": "dashboard_post_broadcasts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Broadcasts" ], "summary": "List broadcasts", "operationId": "dashboard_get_broadcasts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/broadcasts/{id}": { "get": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Retrieve a broadcast", "operationId": "dashboard_get_broadcasts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Update a draft broadcast", "operationId": "dashboard_patch_broadcasts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Delete a broadcast", "operationId": "dashboard_delete_broadcasts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/broadcasts/{id}/cancel": { "post": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Cancel a scheduled or queued broadcast", "operationId": "dashboard_post_broadcasts_id_cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/broadcasts/{id}/duplicate": { "post": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Duplicate a broadcast as a draft", "operationId": "dashboard_post_broadcasts_id_duplicate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/broadcasts/{id}/send": { "post": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Send a broadcast now or at scheduled_at", "operationId": "dashboard_post_broadcasts_id_send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/broadcasts/{id}/test": { "post": { "tags": [ "Dashboard: Broadcasts" ], "summary": "Send a personalised test of a broadcast (up to 5 addresses)", "operationId": "dashboard_post_dashboard_broadcasts_id_test", "description": "Requires the dashboard Origin header (CSRF). Existing contacts are personalised with their data; the subject is prefixed with [Test].", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 5 } ] } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "to": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/contacts": { "post": { "tags": [ "Dashboard: Contacts" ], "summary": "Create (or update) a contact", "operationId": "dashboard_post_contacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Contacts" ], "summary": "List contacts", "operationId": "dashboard_get_contacts", "parameters": [ { "name": "segment_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "audience_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Legacy alias of segment_id." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Prefix of the e-mail, first or last name (Pidgely extension)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/contacts/batch": { "post": { "tags": [ "Dashboard: Contacts" ], "summary": "Upsert up to 1,000 contacts (Pidgely extension)", "operationId": "dashboard_post_contacts_batch", "description": "Each row is saved independently; invalid rows are reported in errors with their index.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/ContactInput" } }, "segment_id": { "type": "string", "format": "uuid", "description": "Added to every row." } }, "required": [ "contacts" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBatchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/contacts/{key}": { "get": { "tags": [ "Dashboard: Contacts" ], "summary": "Retrieve a contact", "operationId": "dashboard_get_contacts_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Contacts" ], "summary": "Update a contact (unsubscribed syncs the suppression list)", "operationId": "dashboard_patch_contacts_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Contacts" ], "summary": "Delete a contact", "operationId": "dashboard_delete_contacts_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "contact": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/contacts/{key}/segments": { "get": { "tags": [ "Dashboard: Contacts" ], "summary": "List a contact's segments", "operationId": "dashboard_get_contacts_key_segments", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/contacts/{key}/segments/{segment_id}": { "post": { "tags": [ "Dashboard: Contacts" ], "summary": "Add a contact to a segment", "operationId": "dashboard_post_contacts_key_segments_segment_id", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Segment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Contacts" ], "summary": "Remove a contact from a segment", "operationId": "dashboard_delete_contacts_key_segments_segment_id", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or e-mail address" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Segment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "segment_id": { "type": "string", "format": "uuid" }, "audienceId": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/domains": { "post": { "tags": [ "Dashboard: Domains" ], "summary": "Create a domain", "operationId": "dashboard_post_domains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomain" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Domains" ], "summary": "List domains", "operationId": "dashboard_get_domains", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/domains/{id}": { "get": { "tags": [ "Dashboard: Domains" ], "summary": "Retrieve a domain", "operationId": "dashboard_get_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Domains" ], "summary": "Update a domain", "operationId": "dashboard_patch_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ] }, "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Domains" ], "summary": "Delete a domain", "operationId": "dashboard_delete_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/domains/{id}/verify": { "post": { "tags": [ "Dashboard: Domains" ], "summary": "Verify a domain's DNS records", "operationId": "dashboard_post_domains_id_verify", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/emails": { "post": { "tags": [ "Dashboard: Emails" ], "summary": "Send an email", "operationId": "dashboard_post_emails", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 256 }, "description": "Replays the stored response for 24 hours; a different body gets 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmail" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Any member." }, "get": { "tags": [ "Dashboard: Emails" ], "summary": "List sent emails", "operationId": "dashboard_get_emails", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated last_event values (queued, scheduled, delivered, delivery_delayed, bounced, complained, suppressed, failed, canceled). Pidgely extension." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Recipient address (exact), or an end date when not an address. Pidgely extension." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Substring of the subject or From. Pidgely extension." }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start date (YYYY-MM-DD or RFC 3339). Alias: since." }, { "name": "since", "in": "query", "schema": { "type": "string" } }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "End date (inclusive day, or RFC 3339 instant)." }, { "name": "recipient", "in": "query", "schema": { "type": "string" }, "description": "Recipient address (alias of to)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/emails/batch": { "post": { "tags": [ "Dashboard: Emails" ], "summary": "Send up to 100 emails", "operationId": "dashboard_post_emails_batch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 256 }, "description": "Replays the stored response for 24 hours; a different body gets 409." }, { "name": "x-batch-validation", "in": "header", "schema": { "type": "string", "enum": [ "strict", "permissive" ] }, "description": "strict (default): all or nothing; permissive: valid items are sent, invalid ones reported in errors." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SendEmail" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Any member." } }, "/dashboard/emails/{email_id}/attachments": { "get": { "tags": [ "Dashboard: Emails" ], "summary": "List an email's attachments", "operationId": "dashboard_get_emails_email_id_attachments", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Email id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/emails/{email_id}/attachments/{id}": { "get": { "tags": [ "Dashboard: Emails" ], "summary": "Retrieve an attachment", "operationId": "dashboard_get_emails_email_id_attachments_id", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Email id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Attachment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAttachment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/emails/{id}": { "get": { "tags": [ "Dashboard: Emails" ], "summary": "Retrieve an email", "operationId": "dashboard_get_emails_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Emails" ], "summary": "Reschedule a scheduled email", "operationId": "dashboard_patch_emails_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string" } }, "required": [ "scheduled_at" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/emails/{id}/cancel": { "post": { "tags": [ "Dashboard: Emails" ], "summary": "Cancel a scheduled email", "operationId": "dashboard_post_emails_id_cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Any member." } }, "/dashboard/emails/{id}/events": { "get": { "tags": [ "Dashboard: Emails" ], "summary": "Delivery timeline of an email", "operationId": "get_dashboard_emails_id_events", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailEvent" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } }, "required": [ "object", "data", "deliveries" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/dashboard/organization": { "get": { "tags": [ "Dashboard: Organization" ], "summary": "Current organization", "operationId": "get_dashboard_organization", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Organization" ], "summary": "Rename the organization (admin)", "operationId": "patch_dashboard_organization", "description": "Requires the dashboard Origin header (CSRF).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] }, "delete": { "tags": [ "Dashboard: Organization" ], "summary": "Delete the organization (owner)", "operationId": "dashboard_delete_dashboard_organization", "description": "Requires the dashboard Origin header (CSRF). Suspends the organization and revokes its keys and sessions at once; data is purged asynchronously.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string", "description": "The organization's exact name." } }, "required": [ "confirm" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/segments": { "post": { "tags": [ "Dashboard: Segments" ], "summary": "Create a segment", "operationId": "dashboard_post_segments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Segments" ], "summary": "List segments", "operationId": "dashboard_get_segments", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/segments/{id}": { "get": { "tags": [ "Dashboard: Segments" ], "summary": "Retrieve a segment", "operationId": "dashboard_get_segments_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "delete": { "tags": [ "Dashboard: Segments" ], "summary": "Delete a segment", "operationId": "dashboard_delete_segments_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "patch": { "tags": [ "Dashboard: Segments" ], "summary": "Rename a segment", "operationId": "dashboard_patch_segments_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/segments/{id}/contacts": { "get": { "tags": [ "Dashboard: Segments" ], "summary": "List a segment's contacts", "operationId": "dashboard_get_segments_id_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/suppressions": { "post": { "tags": [ "Dashboard: Suppressions" ], "summary": "Suppress an address", "operationId": "dashboard_post_suppressions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Suppressions" ], "summary": "List suppressions", "operationId": "dashboard_get_suppressions", "parameters": [ { "name": "origin", "in": "query", "schema": { "type": "string", "enum": [ "bounce", "complaint", "manual", "unsubscribe" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Prefix of the e-mail address (Pidgely extension)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/suppressions/batch/add": { "post": { "tags": [ "Dashboard: Suppressions" ], "summary": "Suppress up to 100 addresses", "operationId": "dashboard_post_suppressions_batch_add", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } } }, "required": [ "emails" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/suppressions/batch/remove": { "post": { "tags": [ "Dashboard: Suppressions" ], "summary": "Remove up to 100 suppressions", "operationId": "dashboard_post_suppressions_batch_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deleted" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/suppressions/{id}": { "get": { "tags": [ "Dashboard: Suppressions" ], "summary": "Retrieve a suppression by id or email", "operationId": "dashboard_get_suppressions_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suppression id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "delete": { "tags": [ "Dashboard: Suppressions" ], "summary": "Remove a suppression by id or email", "operationId": "dashboard_delete_suppressions_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suppression id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/team/invites": { "get": { "tags": [ "Dashboard: Team" ], "summary": "List pending invitations (admin)", "operationId": "get_dashboard_team_invites", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } }, "required": [ "object", "has_more", "data" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] }, "post": { "tags": [ "Dashboard: Team" ], "summary": "Invite someone by e-mail (admin)", "operationId": "post_dashboard_team_invites", "description": "Requires the dashboard Origin header (CSRF).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/dashboard/team/invites/{id}": { "delete": { "tags": [ "Dashboard: Team" ], "summary": "Revoke an invitation (admin)", "operationId": "delete_dashboard_team_invites_id", "description": "Requires the dashboard Origin header (CSRF).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/dashboard/team/invites/{id}/resend": { "post": { "tags": [ "Dashboard: Team" ], "summary": "Re-send an invitation with a new link (admin)", "operationId": "dashboard_post_dashboard_team_invites_id_resend", "description": "Requires the dashboard Origin header (CSRF).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/team/members": { "get": { "tags": [ "Dashboard: Team" ], "summary": "List members", "operationId": "get_dashboard_team_members", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "object", "has_more", "data" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/dashboard/team/members/{user_id}": { "patch": { "tags": [ "Dashboard: Team" ], "summary": "Change a member's role (owners manage ownership)", "operationId": "patch_dashboard_team_members_user_id", "description": "Requires the dashboard Origin header (CSRF).", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "User id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] }, "delete": { "tags": [ "Dashboard: Team" ], "summary": "Remove a member (or leave)", "operationId": "delete_dashboard_team_members_user_id", "description": "Requires the dashboard Origin header (CSRF).", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "User id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/dashboard/templates": { "post": { "tags": [ "Dashboard: Templates" ], "summary": "Create a template", "operationId": "dashboard_post_templates", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Templates" ], "summary": "List templates", "operationId": "dashboard_get_templates", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/templates/{key}": { "get": { "tags": [ "Dashboard: Templates" ], "summary": "Retrieve a template (draft)", "operationId": "dashboard_get_templates_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Templates" ], "summary": "Update a template draft", "operationId": "dashboard_patch_templates_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Templates" ], "summary": "Delete a template", "operationId": "dashboard_delete_templates_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/templates/{key}/duplicate": { "post": { "tags": [ "Dashboard: Templates" ], "summary": "Duplicate a template", "operationId": "dashboard_post_templates_key_duplicate", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/templates/{key}/preview": { "post": { "tags": [ "Dashboard: Templates" ], "summary": "Render the draft with variables (Pidgely extension)", "operationId": "dashboard_post_templates_key_preview", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreview" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/templates/{key}/publish": { "post": { "tags": [ "Dashboard: Templates" ], "summary": "Publish the draft", "operationId": "dashboard_post_templates_key_publish", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/usage": { "get": { "tags": [ "Dashboard: Organization" ], "summary": "Usage today and this month with plan limits", "operationId": "get_dashboard_usage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "today": { "$ref": "#/components/schemas/Usage" }, "month": { "$ref": "#/components/schemas/Usage" }, "plan": { "type": "string" }, "daily_quota": { "type": "integer" }, "monthly_quota": { "type": [ "integer", "null" ] }, "max_domains": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/DailyUsage" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 400, "default": 30 }, "description": "Length of the daily series ending today." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Series start (overrides days)." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Series end (default today)." } ] } }, "/dashboard/webhooks": { "post": { "tags": [ "Dashboard: Webhooks" ], "summary": "Create a webhook (Resend event names, svix-* signatures)", "operationId": "dashboard_post_webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "endpoint", "events" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "signing_secret": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "get": { "tags": [ "Dashboard: Webhooks" ], "summary": "List webhooks", "operationId": "dashboard_get_webhooks", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/webhooks/{id}": { "get": { "tags": [ "Dashboard: Webhooks" ], "summary": "Retrieve a webhook", "operationId": "dashboard_get_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Dashboard: Webhooks" ], "summary": "Update a webhook", "operationId": "dashboard_patch_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." }, "delete": { "tags": [ "Dashboard: Webhooks" ], "summary": "Delete a webhook", "operationId": "dashboard_delete_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/webhooks/{id}/deliveries": { "get": { "tags": [ "Dashboard: Webhooks" ], "summary": "Recent delivery attempts", "operationId": "dashboard_get_dashboard_webhooks_id_deliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/dashboard/webhooks/{id}/signing-secret/rotate": { "post": { "tags": [ "Dashboard: Webhooks" ], "summary": "Rotate the signing secret", "operationId": "dashboard_post_webhooks_id_signing_secret_rotate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "signing_secret": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ], "description": "Requires the dashboard Origin (CSRF). Admins and owners." } }, "/dashboard/webhooks/{id}/test": { "post": { "tags": [ "Dashboard: Webhooks" ], "summary": "Send a signed test event now (admin)", "operationId": "dashboard_post_dashboard_webhooks_id_test", "description": "Requires the dashboard Origin header (CSRF).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAttempt" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "session": [] } ] } }, "/domains": { "post": { "tags": [ "Domains" ], "summary": "Create a domain", "operationId": "post_domains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomain" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Domains" ], "summary": "List domains", "operationId": "get_domains", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/domains/{id}": { "get": { "tags": [ "Domains" ], "summary": "Retrieve a domain", "operationId": "get_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Domains" ], "summary": "Update a domain", "operationId": "patch_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ] }, "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Domains" ], "summary": "Delete a domain", "operationId": "delete_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/domains/{id}/verify": { "post": { "tags": [ "Domains" ], "summary": "Verify a domain's DNS records", "operationId": "post_domains_id_verify", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/emails": { "post": { "tags": [ "Emails" ], "summary": "Send an email", "operationId": "post_emails", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 256 }, "description": "Replays the stored response for 24 hours; a different body gets 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmail" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Emails" ], "summary": "List sent emails", "operationId": "get_emails", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated last_event values (queued, scheduled, delivered, delivery_delayed, bounced, complained, suppressed, failed, canceled). Pidgely extension." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Recipient address (exact), or an end date when not an address. Pidgely extension." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Substring of the subject or From. Pidgely extension." }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start date (YYYY-MM-DD or RFC 3339). Alias: since." }, { "name": "since", "in": "query", "schema": { "type": "string" } }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "End date (inclusive day, or RFC 3339 instant)." }, { "name": "recipient", "in": "query", "schema": { "type": "string" }, "description": "Recipient address (alias of to)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/emails/batch": { "post": { "tags": [ "Emails" ], "summary": "Send up to 100 emails", "operationId": "post_emails_batch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 256 }, "description": "Replays the stored response for 24 hours; a different body gets 409." }, { "name": "x-batch-validation", "in": "header", "schema": { "type": "string", "enum": [ "strict", "permissive" ] }, "description": "strict (default): all or nothing; permissive: valid items are sent, invalid ones reported in errors." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SendEmail" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/emails/{email_id}/attachments": { "get": { "tags": [ "Emails" ], "summary": "List an email's attachments", "operationId": "get_emails_email_id_attachments", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Email id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/emails/{email_id}/attachments/{id}": { "get": { "tags": [ "Emails" ], "summary": "Retrieve an attachment", "operationId": "get_emails_email_id_attachments_id", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Email id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Attachment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAttachment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/emails/{id}": { "get": { "tags": [ "Emails" ], "summary": "Retrieve an email", "operationId": "get_emails_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Emails" ], "summary": "Reschedule a scheduled email", "operationId": "patch_emails_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string" } }, "required": [ "scheduled_at" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/emails/{id}/cancel": { "post": { "tags": [ "Emails" ], "summary": "Cancel a scheduled email", "operationId": "post_emails_id_cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/files/attachments/{tenant}/{email}/{id}": { "get": { "tags": [ "Public" ], "summary": "Download an attachment (signed link from download_url)", "operationId": "get_files_attachments_tenant_email_id", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant id" }, { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Email id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Attachment id" }, { "name": "expires", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [] } }, "/healthz": { "get": { "tags": [ "Operations" ], "summary": "Liveness", "operationId": "get_healthz", "responses": { "200": { "description": "ok", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "security": [] } }, "/me": { "get": { "tags": [ "Me" ], "summary": "Current user, organization and memberships", "operationId": "get_me", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "Me" ], "summary": "Update profile", "operationId": "patch_me", "description": "Requires the dashboard Origin header (CSRF).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "locale": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/me/organization": { "post": { "tags": [ "Me" ], "summary": "Switch the session's organization", "operationId": "post_me_organization", "description": "Requires the dashboard Origin header (CSRF).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid" } }, "required": [ "organization_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/me/password": { "post": { "tags": [ "Me" ], "summary": "Change password (other sessions are revoked)", "operationId": "post_me_password", "description": "Requires the dashboard Origin header (CSRF).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } }, "required": [ "current_password", "new_password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "security": [ { "session": [] } ] } }, "/public/waitlist": { "post": { "tags": [ "Public" ], "summary": "Join the waitlist (CORS, 5/min per IP, idempotent per e-mail)", "operationId": "post_public_waitlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [] } }, "/readyz": { "get": { "tags": [ "Operations" ], "summary": "Readiness (database reachable)", "operationId": "get_readyz", "responses": { "200": { "description": "ready", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "database unavailable" } }, "security": [] } }, "/segments": { "post": { "tags": [ "Segments" ], "summary": "Create a segment", "operationId": "post_segments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Segments" ], "summary": "List segments", "operationId": "get_segments", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/segments/{id}": { "get": { "tags": [ "Segments" ], "summary": "Retrieve a segment", "operationId": "get_segments_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Segments" ], "summary": "Delete a segment", "operationId": "delete_segments_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Segments" ], "summary": "Rename a segment", "operationId": "patch_segments_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/segments/{id}/contacts": { "get": { "tags": [ "Segments" ], "summary": "List a segment's contacts", "operationId": "get_segments_id_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/suppressions": { "post": { "tags": [ "Suppressions" ], "summary": "Suppress an address", "operationId": "post_suppressions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Suppressions" ], "summary": "List suppressions", "operationId": "get_suppressions", "parameters": [ { "name": "origin", "in": "query", "schema": { "type": "string", "enum": [ "bounce", "complaint", "manual", "unsubscribe" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Prefix of the e-mail address (Pidgely extension)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/suppressions/batch/add": { "post": { "tags": [ "Suppressions" ], "summary": "Suppress up to 100 addresses", "operationId": "post_suppressions_batch_add", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } } }, "required": [ "emails" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/suppressions/batch/remove": { "post": { "tags": [ "Suppressions" ], "summary": "Remove up to 100 suppressions", "operationId": "post_suppressions_batch_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deleted" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/suppressions/{id}": { "get": { "tags": [ "Suppressions" ], "summary": "Retrieve a suppression by id or email", "operationId": "get_suppressions_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suppression id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Suppressions" ], "summary": "Remove a suppression by id or email", "operationId": "delete_suppressions_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suppression id or e-mail address" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/templates": { "post": { "tags": [ "Templates" ], "summary": "Create a template", "operationId": "post_templates", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Templates" ], "summary": "List templates", "operationId": "get_templates", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/templates/{key}": { "get": { "tags": [ "Templates" ], "summary": "Retrieve a template (draft)", "operationId": "get_templates_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Templates" ], "summary": "Update a template draft", "operationId": "patch_templates_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "operationId": "delete_templates_key", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/templates/{key}/duplicate": { "post": { "tags": [ "Templates" ], "summary": "Duplicate a template", "operationId": "post_templates_key_duplicate", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/templates/{key}/preview": { "post": { "tags": [ "Templates" ], "summary": "Render the draft with variables (Pidgely extension)", "operationId": "post_templates_key_preview", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreview" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/templates/{key}/publish": { "post": { "tags": [ "Templates" ], "summary": "Publish the draft", "operationId": "post_templates_key_publish", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/u/{token}": { "get": { "tags": [ "Public" ], "summary": "Unsubscribe confirmation page", "operationId": "get_u_token", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signed unsubscribe token" } ], "responses": { "200": { "description": "HTML page", "content": { "text/html": { "schema": { "type": "string" } } } } }, "security": [] }, "post": { "tags": [ "Public" ], "summary": "RFC 8058 one-click unsubscribe", "operationId": "post_u_token", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signed unsubscribe token" } ], "responses": { "200": { "description": "Unsubscribed (HTML)", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Invalid link" } }, "security": [] } }, "/v1/api-keys": { "post": { "tags": [ "Native API (v1)" ], "summary": "Create an API key", "operationId": "native_post_v1_api_keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "full", "sending" ] }, "domain_id": { "type": "string", "format": "uuid" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Native API (v1)" ], "summary": "List API keys", "operationId": "native_get_v1_api_keys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/api-keys/{id}": { "delete": { "tags": [ "Native API (v1)" ], "summary": "Revoke an API key", "operationId": "native_delete_v1_api_keys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "204": { "description": "Revoked" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/domains": { "post": { "tags": [ "Native API (v1)" ], "summary": "Create a domain", "operationId": "native_post_v1_domains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomain" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Native API (v1)" ], "summary": "List domains", "operationId": "native_get_v1_domains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/domains/{id}": { "get": { "tags": [ "Native API (v1)" ], "summary": "Retrieve a domain", "operationId": "native_get_v1_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Native API (v1)" ], "summary": "Delete a domain", "operationId": "native_delete_v1_domains_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "204": { "description": "Deleted" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/domains/{id}/verify": { "post": { "tags": [ "Native API (v1)" ], "summary": "Verify DNS now", "operationId": "native_post_v1_domains_id_verify", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/emails": { "post": { "tags": [ "Native API (v1)" ], "summary": "Send an email", "operationId": "native_post_v1_emails", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmail" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Native API (v1)" ], "summary": "List emails", "operationId": "native_get_v1_emails", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/emails/batch": { "post": { "tags": [ "Native API (v1)" ], "summary": "Send up to 100 emails atomically", "operationId": "native_post_v1_emails_batch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SendEmail" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Id" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/emails/{id}": { "get": { "tags": [ "Native API (v1)" ], "summary": "Email with deliveries and timeline", "operationId": "native_get_v1_emails_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/emails/{id}/cancel": { "post": { "tags": [ "Native API (v1)" ], "summary": "Cancel a scheduled email", "operationId": "native_post_v1_emails_id_cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/suppressions": { "get": { "tags": [ "Native API (v1)" ], "summary": "List suppressions", "operationId": "native_get_v1_suppressions", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "Native API (v1)" ], "summary": "Add a suppression", "operationId": "native_post_v1_suppressions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" } }, "required": [ "address" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/suppressions/{address}": { "delete": { "tags": [ "Native API (v1)" ], "summary": "Remove a suppression", "operationId": "native_delete_v1_suppressions_address", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "E-mail address" } ], "responses": { "204": { "description": "Removed" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/usage": { "get": { "tags": [ "Native API (v1)" ], "summary": "Today's usage and quota", "operationId": "native_get_v1_usage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "$ref": "#/components/schemas/Usage" }, "daily_quota": { "type": "integer" }, "status": { "type": "string" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/webhooks": { "post": { "tags": [ "Native API (v1)" ], "summary": "Create a webhook (native event names)", "operationId": "native_post_v1_webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Native API (v1)" ], "summary": "List webhooks", "operationId": "native_get_v1_webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/webhooks/{id}": { "delete": { "tags": [ "Native API (v1)" ], "summary": "Delete a webhook", "operationId": "native_delete_v1_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "204": { "description": "Deleted" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook (Resend event names, svix-* signatures)", "operationId": "post_webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "endpoint", "events" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "signing_secret": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "operationId": "get_webhooks", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100)." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the last item of the previous page (older items)." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Id of the first item of the current page (newer items)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a webhook", "operationId": "get_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "operationId": "patch_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "operationId": "delete_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } }, "/webhooks/{id}/signing-secret/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the signing secret", "operationId": "post_webhooks_id_signing_secret_rotate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "signing_secret": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "security": [ { "apiKey": [] } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key `pdg__`." }, "session": { "type": "apiKey", "in": "cookie", "name": "pdg_session", "description": "Dashboard session cookie (HttpOnly, SameSite=Lax). Unsafe methods also need an allowed Origin." }, "admin": { "type": "http", "scheme": "bearer", "description": "Operator token (ADMIN_TOKEN)." } }, "responses": { "Unauthorized": { "description": "Missing or restricted credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } }, "Forbidden": { "description": "Invalid key, unverified domain, plan limit, CSRF or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } }, "Invalid": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } }, "TooMany": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendError" } } } } }, "schemas": { "ResendError": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "name": { "type": "string", "description": "Machine-readable error name (validation_error, not_found, missing_api_key, invalid_api_key, restricted_api_key, rate_limit_exceeded, daily_quota_exceeded, monthly_quota_exceeded, invalid_idempotent_request, csrf_failed, insufficient_role, ...)." }, "message": { "type": "string" }, "field": { "type": "string", "description": "Offending field, when known (Pidgely addition)." }, "request_id": { "type": "string", "description": "Request id (also in the X-Request-Id header)." } }, "required": [ "statusCode", "name", "message" ] }, "NativeError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message" ] } } }, "ObjectId": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "object", "id" ] }, "Id": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "Deleted": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] }, "Status": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] }, "Tag": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } }, "required": [ "name", "value" ] }, "Attachment": { "type": "object", "properties": { "filename": { "type": "string" }, "content": { "type": "string", "description": "Base64 content. Use either content or path." }, "path": { "type": "string", "description": "http(s) URL downloaded at send time (SSRF-guarded, 40MB budget, no redirects)." }, "content_type": { "type": "string" }, "content_id": { "type": "string", "description": "Makes the attachment inline (`cid:` in HTML)." } } }, "TemplateRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Template id or alias (published version is used)." }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" } ] } } }, "required": [ "id" ] }, "SendEmail": { "type": "object", "properties": { "from": { "type": "string", "description": "`Name `; may come from the template." }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "cc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "bcc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string", "description": "Generated from html when omitted." }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "scheduled_at": { "type": "string", "description": "ISO 8601 or natural language (`in 1 hour`, `tomorrow at 9am`); within 30 days." }, "template": { "$ref": "#/components/schemas/TemplateRef" }, "topic_id": { "type": "string", "description": "Not supported yet; a non-empty value is rejected." }, "stream": { "type": "string", "description": "Pidgely extension: `transactional` (default) or `broadcast` (adds RFC 8058 unsubscribe).", "enum": [ "transactional", "broadcast" ] } }, "required": [ "to" ] }, "BatchResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Id" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "string" } } } } }, "required": [ "data" ] }, "Email": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "reply_to": { "type": "array", "items": { "type": "string" } }, "from": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "scheduled_at": { "type": [ "string", "null" ], "description": "Timestamp in Resend format, or null." }, "last_event": { "type": "string", "enum": [ "queued", "scheduled", "sent", "delivered", "delivery_delayed", "bounced", "complained", "suppressed", "failed", "canceled" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } }, "EmailAttachment": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "content_type": { "type": "string" }, "content_disposition": { "type": "string", "enum": [ "attachment", "inline" ] }, "content_id": { "type": [ "string", "null" ] }, "download_url": { "type": "string", "description": "Signed link, valid for 1 hour." }, "expires_at": { "type": "string" } } }, "DomainRecord": { "type": "object", "properties": { "record": { "type": "string", "enum": [ "DKIM", "SPF", "DMARC" ] }, "name": { "type": "string", "description": "Relative to the domain." }, "type": { "type": "string", "enum": [ "TXT", "MX" ] }, "ttl": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "integer" } } }, "Domain": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed" ] }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "region": { "type": "string" }, "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" }, "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ] }, "capabilities": { "type": "object", "properties": { "sending": { "type": "string" }, "receiving": { "type": "string" } } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRecord" } } } }, "CreateDomain": { "type": "object", "properties": { "name": { "type": "string" }, "region": { "type": "string" }, "custom_return_path": { "type": "string", "description": "Bounce subdomain label (default `bounces`)." }, "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ] }, "open_tracking": { "type": "boolean", "description": "Accepted, not supported yet (always false)." }, "click_tracking": { "type": "boolean", "description": "Accepted, not supported yet." }, "capabilities": { "type": "object", "properties": { "sending": { "type": "string" }, "receiving": { "type": "string", "description": "`enabled` is rejected (receiving not supported yet)." } } } }, "required": [ "name" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "last_used_at": { "type": [ "string", "null" ], "description": "Timestamp in Resend format, or null." }, "prefix": { "type": "string", "description": "Public token prefix (`pdg_`), to recognise a key." }, "domain_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Domain the key is restricted to, if any." } } }, "CreatedApiKey": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "Shown once: `pdg__`." } } }, "Webhook": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "endpoint": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "signing_secret": { "type": "string" } } }, "Suppression": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "origin": { "type": "string", "enum": [ "bounce", "complaint", "manual", "unsubscribe" ] }, "source_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "ContactInput": { "type": "object", "properties": { "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "topics": { "type": "array", "description": "Not supported yet." } } }, "Contact": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": {}, "type": { "type": "string", "enum": [ "string", "number", "boolean" ] } } } } } }, "Segment": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "contacts_count": { "type": "integer", "description": "Number of contacts in the segment." } } }, "BroadcastInput": { "type": "object", "properties": { "segment_id": { "type": "string", "format": "uuid" }, "audience_id": { "type": "string", "format": "uuid", "description": "Legacy alias of segment_id." }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "html": { "type": "string", "description": "Supports `{{{FIRST_NAME|there}}}`, `{{{contact.}}}`, `{{{RESEND_UNSUBSCRIBE_URL}}}` and `{{{PIDGELY_UNSUBSCRIBE_URL}}}`." }, "text": { "type": "string" }, "name": { "type": "string" }, "preview_text": { "type": "string" }, "send": { "type": "boolean" }, "scheduled_at": { "type": "string" }, "topic_id": { "type": "string", "description": "Not supported yet." } } }, "Broadcast": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "segment_id": { "type": [ "string", "null" ] }, "audience_id": { "type": [ "string", "null" ] }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "type": "array", "items": { "type": "string" } }, "preview_text": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "queued", "sending", "sent", "canceled", "failed" ] }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "scheduled_at": { "type": [ "string", "null" ], "description": "Timestamp in Resend format, or null." }, "sent_at": { "type": [ "string", "null" ], "description": "Timestamp in Resend format, or null." }, "topic_id": { "type": "null" }, "recipients": { "type": "integer" }, "stats": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Deliveries by status (Pidgely extension)." } } }, "TemplateVariable": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "updated_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "TemplateInput": { "type": "object", "properties": { "name": { "type": "string" }, "alias": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "html": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "key", "type" ] } } } }, "Template": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "current_version_id": { "type": [ "string", "null" ] }, "alias": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "updated_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "description": "Timestamp in Resend format, or null." }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "type": "array", "items": { "type": "string" } }, "html": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } }, "has_unpublished_versions": { "type": "boolean" } } }, "User": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "pt-br", "es" ] }, "email_verified": { "type": "boolean" }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "Organization": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "sandbox", "active", "paused", "suspended" ] }, "daily_quota": { "type": "integer" }, "monthly_quota": { "type": [ "integer", "null" ] }, "max_domains": { "type": [ "integer", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "SessionUser": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "organization": { "$ref": "#/components/schemas/Organization" } }, "required": [ "user", "organization" ] }, "Me": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "organization": { "$ref": "#/components/schemas/Organization" }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string" } } } }, "session_expires_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "Member": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "joined_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "Invite": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "expires_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } } }, "Usage": { "type": "object", "properties": { "accepted": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" } } }, "WaitlistInput": { "type": "object", "properties": { "email": { "type": "string" }, "company": { "type": "string" }, "use_case": { "type": "string" }, "locale": { "type": "string", "description": "en, pt-br, es, ..." }, "source": { "type": "string" }, "marketing_consent": { "type": "boolean" }, "website": { "type": "string", "description": "Honeypot: must be empty; when filled the request succeeds and nothing is stored." } }, "required": [ "email" ] }, "DailyUsage": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "accepted": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" } }, "required": [ "date", "accepted", "delivered", "bounced", "complained" ] }, "WebhookAttempt": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_attempt" ] }, "id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "attempt": { "type": "integer" }, "test": { "type": "boolean" }, "success": { "type": "boolean" }, "status_code": { "type": "integer", "description": "0 when no response was received." }, "latency_ms": { "type": "integer" }, "error": { "type": "string" }, "attempted_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } }, "required": [ "id", "webhook_id", "event_type", "success", "status_code", "latency_ms", "attempted_at" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipient": { "type": "string" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "deferred", "delivered", "bounced", "complained", "suppressed", "failed", "canceled" ] }, "attempts": { "type": "integer" }, "last_response": { "type": "string" }, "transport": { "type": "string" }, "first_attempt_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "recipient", "kind", "status", "attempts", "updated_at" ] }, "EmailEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "email.queued, email.delivered, email.deferred, email.bounced, email.failed, email.complained, email.suppressed, email.unsubscribed, email.canceled" }, "recipient": { "type": "string" }, "data": { "type": "object", "description": "Event payload: recipient, transport, remote_host, response (delivered); attempt, class, code, enhanced_code, message, next_attempt_at (deferred); type, source, code, enhanced_code, message (bounced); reason (suppressed/failed); from, subject, to, tags, scheduled_at (queued).", "additionalProperties": true }, "created_at": { "type": "string", "description": "Timestamp in Resend format (`2026-10-12 16:44:41.000000+00`)." } }, "required": [ "id", "type", "data", "created_at" ] }, "ContactBatchResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "index", "id" ] } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "index", "message" ] } } }, "required": [ "object", "data", "errors" ] }, "TemplatePreview": { "type": "object", "properties": { "object": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "type": "array", "items": { "type": "string" } }, "html": { "type": "string" }, "text": { "type": "string" }, "missing_variables": { "type": "array", "items": { "type": "string" } } }, "required": [ "subject", "html", "text", "missing_variables" ] } } } }