{ "openapi": "3.1.0", "info": { "title": "Bytesms API", "version": "1.0.0", "summary": "Resend-compatible email API: emails, domains, API keys, templates, audiences, broadcasts.", "description": "Authenticate with `Authorization: Bearer tp_live_…`. Rate limit: 10 requests/second per workspace by default (ratelimit-* headers). Errors: `{ statusCode, message, name }`. Docs: https://bytesms.com/docs", "contact": { "url": "https://bytesms.com/docs" } }, "servers": [ { "url": "https://api.bytesms.com/api" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Emails", "description": "Send, batch, schedule, retrieve and cancel transactional email." }, { "name": "Domains", "description": "Sending domains and their DNS records." }, { "name": "API keys", "description": "Workspace API keys." }, { "name": "Templates", "description": "Reusable content with variables." }, { "name": "Audiences", "description": "Audiences and their contacts." }, { "name": "Broadcasts", "description": "Marketing email to an audience." }, { "name": "Webhooks", "description": "Events Bytesms POSTs to your endpoints (configured in the dashboard)." } ], "paths": { "/v1/emails": { "post": { "operationId": "sendEmail", "summary": "Send an email", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailId" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "description": "Sending not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_from_address": { "value": { "statusCode": 403, "message": "The example.com domain is not verified in this workspace.", "name": "invalid_from_address" } }, "restricted_api_key": { "value": { "statusCode": 403, "message": "This API key is restricted to sending from example.com.", "name": "restricted_api_key" } }, "sending_paused": { "value": { "statusCode": 403, "message": "Sending is paused for this workspace.", "name": "sending_paused" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_conflict": { "value": { "statusCode": 409, "message": "This Idempotency-Key was already used with a different request body.", "name": "idempotency_key_conflict" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Retries with the same key and body return the first response for 24 hours; a different body with the same key is 409 idempotency_key_conflict." } ], "x-permission": "sending_access or full_access" }, "get": { "operationId": "listEmails", "summary": "List emails", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSummary" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Page size." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Email id cursor: older emails." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Email id cursor: newer emails." } ], "x-permission": "full_access" } }, "/v1/emails/batch": { "post": { "operationId": "sendBatch", "summary": "Send up to 100 emails", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailId" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "All-or-nothing. scheduled_at is not allowed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SendEmailRequest" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Retries with the same key and body return the first response for 24 hours; a different body with the same key is 409 idempotency_key_conflict." } ], "x-permission": "sending_access or full_access" } }, "/v1/emails/{email_id}": { "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id." } ], "get": { "operationId": "getEmail", "summary": "Retrieve an email", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" }, "patch": { "operationId": "updateEmail", "summary": "Reschedule a scheduled email", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "scheduled_at" ] } } } }, "x-permission": "full_access" } }, "/v1/emails/{email_id}/events": { "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id." } ], "get": { "operationId": "listEmailEvents", "summary": "List an email's events", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailEvent" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/emails/{email_id}/cancel": { "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id." } ], "post": { "operationId": "cancelEmail", "summary": "Cancel a scheduled email", "tags": [ "Emails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/domains": { "get": { "operationId": "listDomains", "summary": "List domains", "tags": [ "Domains" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainListItem" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-permission": "full_access" }, "post": { "operationId": "createDomain", "summary": "Create a domain", "tags": [ "Domains" ], "responses": { "201": { "description": "Created (response has no `object` field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_limit_exceeded": { "value": { "statusCode": 403, "message": "Domain limit reached for your plan.", "name": "plan_limit_exceeded" } } } } } }, "409": { "description": "Domain claimed elsewhere", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "domain_in_use": { "value": { "statusCode": 409, "message": "This domain is already verified in another workspace.", "name": "domain_in_use" } }, "domain_pending_elsewhere": { "value": { "statusCode": 409, "message": "This domain was added to another workspace less than 72 hours ago.", "name": "domain_pending_elsewhere" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 253 }, "region": { "type": "string", "enum": [ "ap-southeast-7", "ap-southeast-1", "eu-central-1" ], "default": "ap-southeast-7", "description": "Unavailable regions fall back to the default." }, "custom_return_path": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "default": "send", "description": "Return-path subdomain label; www, mail, smtp, mx, imap, pop, pop3, autodiscover, autoconfig are reserved." } }, "required": [ "name" ] } } } }, "x-permission": "full_access" } }, "/v1/domains/{domain_id}": { "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id." } ], "get": { "operationId": "getDomain", "summary": "Retrieve a domain", "tags": [ "Domains" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" }, "delete": { "operationId": "deleteDomain", "summary": "Delete a domain", "tags": [ "Domains" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "description": "Sending server unreachable; nothing was deleted. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "full_access" } }, "/v1/domains/{domain_id}/verify": { "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id." } ], "post": { "operationId": "verifyDomain", "summary": "Verify a domain", "tags": [ "Domains" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "domain" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "API keys" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-permission": "full_access" }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "tags": [ "API keys" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string", "description": "Full key, returned once." } }, "required": [ "id", "token" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ], "description": "Default full_access, or sending_access when domain_id is set." }, "domain_id": { "type": "string" } }, "required": [ "name" ] } } } }, "x-permission": "full_access" } }, "/v1/api-keys/{api_key_id}": { "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "API key id." } ], "delete": { "operationId": "deleteApiKey", "summary": "Delete an API key", "tags": [ "API keys" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/templates": { "get": { "operationId": "listTemplates", "summary": "List templates", "tags": [ "Templates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "published" ] }, "description": "Filter." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Page size." } ], "x-permission": "full_access" }, "post": { "operationId": "createTemplate", "summary": "Create a template", "tags": [ "Templates" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TemplateInput" } ], "required": [ "name" ] } } } }, "x-permission": "full_access" } }, "/v1/templates/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias." } ], "get": { "operationId": "getTemplate", "summary": "Retrieve a template", "tags": [ "Templates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" }, "patch": { "operationId": "updateTemplate", "summary": "Update a template draft", "tags": [ "Templates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "x-permission": "full_access" }, "delete": { "operationId": "deleteTemplate", "summary": "Delete a template", "tags": [ "Templates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/templates/{id}/publish": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias." } ], "post": { "operationId": "publishTemplate", "summary": "Publish a template", "tags": [ "Templates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/templates/{id}/duplicate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias." } ], "post": { "operationId": "duplicateTemplate", "summary": "Duplicate a template", "tags": [ "Templates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/audiences": { "get": { "operationId": "listAudiences", "summary": "List audiences", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-permission": "full_access" }, "post": { "operationId": "createAudience", "summary": "Create an audience", "tags": [ "Audiences" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "audience" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "object", "id", "name" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ] } } } }, "x-permission": "full_access" } }, "/v1/audiences/{audience_id}": { "parameters": [ { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id." } ], "get": { "operationId": "getAudience", "summary": "Retrieve an audience", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" }, "delete": { "operationId": "deleteAudience", "summary": "Delete an audience", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/audiences/{audience_id}/contacts": { "parameters": [ { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id." } ], "get": { "operationId": "listContacts", "summary": "List contacts", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Page size." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number." } ], "x-permission": "full_access" }, "post": { "operationId": "createContact", "summary": "Create a contact", "tags": [ "Audiences" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ContactInput" } ], "required": [ "email" ] } } } }, "x-permission": "full_access" } }, "/v1/audiences/{audience_id}/contacts/{contact}": { "parameters": [ { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id." }, { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email address." } ], "get": { "operationId": "getContact", "summary": "Retrieve a contact", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "x-permission": "full_access" }, "delete": { "operationId": "deleteContact", "summary": "Delete a contact", "tags": [ "Audiences" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "contact" }, "contact": { "type": "string" }, "deleted": { "const": true } }, "required": [ "object", "contact", "deleted" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/broadcasts": { "get": { "operationId": "listBroadcasts", "summary": "List broadcasts", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } } }, "required": [ "object", "has_more", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BroadcastStatus" }, "description": "Filter by status." }, { "name": "audience_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by audience." } ], "x-permission": "full_access" }, "post": { "operationId": "createBroadcast", "summary": "Create (and optionally send) a broadcast", "tags": [ "Broadcasts" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BroadcastInput" }, { "type": "object", "properties": { "send": { "type": "boolean", "default": false }, "scheduled_at": { "type": "string", "format": "date-time" } } } ], "required": [ "from", "subject" ] } } } }, "x-permission": "full_access" } }, "/v1/broadcasts/{broadcast_id}": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id." } ], "get": { "operationId": "getBroadcast", "summary": "Retrieve a broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" }, "patch": { "operationId": "updateBroadcast", "summary": "Update a draft broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastInput" } } } }, "x-permission": "full_access" }, "delete": { "operationId": "deleteBroadcast", "summary": "Delete a draft or canceled broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } }, "/v1/broadcasts/{broadcast_id}/send": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id." } ], "post": { "operationId": "sendBroadcast", "summary": "Send or schedule a broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time" } } } } } }, "x-permission": "full_access" } }, "/v1/broadcasts/{broadcast_id}/cancel": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id." } ], "post": { "operationId": "cancelBroadcast", "summary": "Cancel a scheduled or queued broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "broadcast" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-permission": "full_access" } } }, "webhooks": { "email.sent": { "post": { "summary": "Email handed to the sending server", "operationId": "webhook_email_sent", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "email.delivered": { "post": { "summary": "Recipient mail server accepted the email", "operationId": "webhook_email_delivered", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "email.delivery_delayed": { "post": { "summary": "Temporary failure, retrying", "operationId": "webhook_email_delivery_delayed", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "email.bounced": { "post": { "summary": "Permanent failure", "operationId": "webhook_email_bounced", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "email.complained": { "post": { "summary": "Spam complaint", "operationId": "webhook_email_complained", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "email.failed": { "post": { "summary": "Email could not be sent", "operationId": "webhook_email_failed", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "domain.created": { "post": { "summary": "Domain added", "operationId": "webhook_domain_created", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "domain.updated": { "post": { "summary": "Domain changed", "operationId": "webhook_domain_updated", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } }, "domain.deleted": { "post": { "summary": "Domain removed", "operationId": "webhook_domain_deleted", "tags": [ "Webhooks" ], "parameters": [ { "name": "bytesms-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" }, { "name": "svix-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id, stable across retries." }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "v1,..\")>" }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-event-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainWebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; otherwise it is retried (8 attempts)." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key starting with tp_live_." } }, "schemas": { "Error": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "name": { "type": "string", "description": "Machine-readable error name, e.g. validation_error, restricted_api_key, daily_quota_exceeded." }, "code": { "type": "string", "description": "Internal code on quota and plan-limit errors (e.g. daily_limit_reached, domain_limit_reached)." }, "limit": { "type": [ "number", "null" ] }, "current": { "type": [ "number", "null" ] } }, "required": [ "statusCode", "message", "name" ] }, "Tag": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{0,256}$" } }, "required": [ "name" ] }, "SendEmailRequest": { "type": "object", "properties": { "from": { "type": "string", "minLength": 3, "description": "Sender, e.g. \"Acme \". Must be on a verified domain (or onboarding@bytesms.com for tests to workspace members). Optional with a template that sets it." }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "Recipient(s). to + cc + bcc: 1-50 recipients." }, "cc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "bcc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "subject": { "type": "string", "minLength": 1, "description": "Optional with a template that sets it." }, "html": { "type": "string" }, "text": { "type": "string", "description": "Generated from html when omitted." }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Future time, at most 30 days ahead. Not allowed in batch sends." }, "tags": { "oneOf": [ { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Tag" } }, { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } } ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Only List-Unsubscribe, List-Unsubscribe-Post (List-Unsubscribe=One-Click with an https List-Unsubscribe) and X-Entity-Ref-ID are added to the message." }, "template": { "type": "object", "properties": { "id": { "type": "string", "description": "Template id or alias." }, "variables": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] } } }, "description": "Render a published template; cannot be combined with html/text.", "required": [ "id" ] }, "attachments": { "description": "Not supported: any non-empty value is rejected with 422 attachments_not_supported." } }, "required": [ "to" ] }, "EmailId": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "EmailEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "type", "created_at", "data" ] }, "EmailSummary": { "type": "object", "properties": { "object": { "const": "email" }, "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "reply_to": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_event": { "type": "string", "enum": [ "queued", "scheduled", "sent", "delivered", "bounced", "complained", "failed", "canceled" ] } }, "required": [ "object", "id", "from", "to", "subject", "created_at", "last_event" ] }, "Email": { "allOf": [ { "$ref": "#/components/schemas/EmailSummary" }, { "type": "object", "properties": { "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EmailEvent" } } } } ] }, "EmailRef": { "type": "object", "properties": { "object": { "const": "email" }, "id": { "type": "string" } }, "required": [ "object", "id" ] }, "DomainRecord": { "type": "object", "properties": { "record": { "type": "string", "enum": [ "DKIM", "RETURN_PATH", "SPF", "DMARC" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "TXT", "CNAME", "MX" ] }, "ttl": { "type": "string" }, "status": { "type": "string", "enum": [ "not_started", "verified", "failed" ] }, "value": { "type": "string" }, "priority": { "type": "integer" } }, "required": [ "record", "name", "type", "ttl", "status", "value" ] }, "DomainStatus": { "type": "string", "enum": [ "not_started", "pending", "verified", "temporary_failure", "failed" ] }, "Domain": { "type": "object", "properties": { "object": { "const": "domain" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainStatus" }, "region": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "custom_return_path": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRecord" } } }, "required": [ "id", "name", "status", "records" ] }, "DomainListItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/DomainStatus" }, "region": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "status" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "domain_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "permission" ] }, "TemplateVariable": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 64 }, "type": { "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "type": [ "string", "number" ] } }, "required": [ "key" ] }, "TemplateInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "alias": { "type": [ "string", "null" ], "maxLength": 64 }, "subject": { "type": [ "string", "null" ], "maxLength": 998 }, "from": { "type": [ "string", "null" ], "maxLength": 320 }, "reply_to": { "type": [ "string", "null" ], "maxLength": 320 }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "variables": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/TemplateVariable" } } } }, "Template": { "type": "object", "properties": { "object": { "const": "template" }, "id": { "type": "string" }, "name": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "from": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } }, "has_unpublished_changes": { "type": "boolean" }, "has_unpublished_versions": { "type": "boolean" }, "published": { "type": [ "object", "null" ], "properties": { "subject": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name", "status" ] }, "TemplateRef": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "template" } }, "required": [ "id", "object" ] }, "Audience": { "type": "object", "properties": { "object": { "const": "audience" }, "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name" ] }, "ContactInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ], "maxLength": 200 }, "last_name": { "type": [ "string", "null" ], "maxLength": 200 }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } }, "Contact": { "type": "object", "properties": { "object": { "const": "contact" }, "id": { "type": "string" }, "audience_id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "audience_id", "email", "unsubscribed" ] }, "BroadcastInput": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "audience_id": { "type": [ "string", "null" ] }, "segment_id": { "type": [ "string", "null" ], "description": "Alias of audience_id." }, "from": { "type": "string", "minLength": 3, "maxLength": 320 }, "reply_to": { "type": [ "string", "null" ], "maxLength": 320 }, "subject": { "type": "string", "minLength": 1, "maxLength": 998 }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ] } } }, "BroadcastStatus": { "type": "string", "enum": [ "draft", "scheduled", "queued", "sending", "sent", "canceled", "failed" ] }, "Broadcast": { "type": "object", "properties": { "object": { "const": "broadcast" }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "audience_id": { "type": [ "string", "null" ] }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/BroadcastStatus" }, "total_recipients": { "type": "integer" }, "sent_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "from", "subject", "status" ] }, "Id": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "Deleted": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "deleted": { "const": true } }, "required": [ "object", "id", "deleted" ] }, "EmailWebhookData": { "type": "object", "properties": { "email_id": { "type": "string" }, "broadcast_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "bounce": { "type": "object", "properties": { "type": { "type": "string" }, "subType": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } } } }, "complaint": { "type": "object", "properties": { "type": { "type": "string" }, "recipients": { "type": "array", "items": { "type": "string" } } } }, "delay": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "dsn": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } } } }, "failed": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] } } } }, "required": [ "email_id", "created_at", "from", "to", "subject" ] }, "EmailWebhookEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailWebhookData" } }, "required": [ "type", "created_at", "data" ] }, "DomainWebhookEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "domain.created", "domain.updated", "domain.deleted" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Domain" } ], "description": "The domain object without `object`." } }, "required": [ "type", "id", "created_at", "data" ] } }, "responses": { "Unauthorized": { "description": "Invalid key, or a sending_access key on a full_access endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "statusCode": 401, "message": "Invalid API key", "name": "unauthorized" } }, "restricted_api_key": { "value": { "statusCode": 401, "message": "This API key is restricted to only send emails.", "name": "restricted_api_key" } } } } } }, "NotFound": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "statusCode": 404, "message": "Not found", "name": "not_found" } } } } } }, "ValidationError": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_error": { "value": { "statusCode": 422, "message": "`to` must contain at least one recipient.", "name": "validation_error" } } } } } }, "RateLimited": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "statusCode": 429, "message": "Too many requests. You can only make 10 requests per second.", "name": "rate_limit_exceeded" } }, "daily_quota_exceeded": { "value": { "statusCode": 429, "message": "Daily email limit reached.", "name": "daily_quota_exceeded" } }, "monthly_quota_exceeded": { "value": { "statusCode": 429, "message": "Email quota exceeded.", "name": "monthly_quota_exceeded" } }, "overage_cap_reached": { "value": { "statusCode": 429, "message": "Overage cap reached.", "name": "overage_cap_reached" } }, "spend_limit_reached": { "value": { "statusCode": 429, "message": "Pay-as-you-go spend limit reached.", "name": "spend_limit_reached" } } } } }, "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait (rate limit)." } } } } } }