{ "openapi": "3.1.0", "info": { "title": "Prontuno API", "version": "1.0.0", "description": "Prontuno Email API lets you send transactional emails, manage sending domains, track message delivery, and handle suppressions. All endpoints require a Bearer token with a Prontuno API key. Each API key belongs to one team; messages, domains, suppressions, credit balance, sending status, and request rate limits are scoped to that team.", "contact": { "email": "support@prontuno.com" } }, "servers": [ { "url": "https://api.prontuno.net" } ], "paths": { "/v1/emails": { "post": { "summary": "Send a single email", "operationId": "sendEmail", "responses": { "202": { "description": "Email request accepted for delivery.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Email identifier in the `email_` format." }, "to": { "type": "string", "format": "email", "description": "Normalized recipient address. Display names supplied in the request are stripped." } }, "required": [ "id", "to" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "emails" ], "additionalProperties": false, "description": "Accepted emails for the request; one entry per accepted recipient." }, "example": { "emails": [ { "id": "email_01kxwz4bfhe00rr3ww02remnap", "to": "hello@example.com" } ] } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "Request validation failed" }, "errors": [ { "code": "missing_subject", "message": "subject is required", "field": "subject", "retryable": false, "suggested_action": "fix_input" }, { "code": "invalid_attachment_encoding", "message": "Attachment encoding must be one of: base64, utf8, ascii, latin1, hex", "field": "attachments.encoding", "value": "rot13", "path": "attachments[0].encoding", "retryable": false, "suggested_action": "fix_input", "meta": { "allowed_values": [ "base64", "utf8", "ascii", "latin1", "hex" ] } } ] } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "402": { "description": "The authenticated team does not have enough credits for every accepted recipient in the request.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "insufficient_credits", "message": "Insufficient credit balance to send this email.", "retryable": false, "suggested_action": "top_up_credits", "available_credits": 0 } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "idempotency_key_conflict", "message": "Idempotency key already used with a different request body", "retryable": false, "suggested_action": "use_new_idempotency_key" } } } } }, "413": { "description": "Request body exceeds the maximum size.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "payload_too_large", "message": "Request body too large. Maximum size is 15MB", "retryable": false, "suggested_action": "fix_input" } } } } }, "415": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "A required service is temporarily unavailable, so the request could not be accepted for delivery. A `credit_check_failed` response means the current team credit balance could not be verified. Wait at least Retry-After and retry with exponential backoff using the same idempotency key and request body.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "credit_check_failed", "message": "Unable to verify credit balance. Please try again later.", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 2, "retry_strategy": "exponential_backoff" } } } } } }, "description": "Validates a single send payload and accepts one message per recipient for asynchronous delivery.", "tags": [ "Emails" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for send and batch-send requests. If a request with the same key was already accepted, the server returns the original accepted response without creating duplicate messages. Keys are scoped per API key and retained for 24 hours. Use a unique value per logical send operation (e.g., a UUID).", "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "RFC 5322-style sender address." }, "to": { "description": "Recipient field accepted as either one RFC 5322 mailbox string or an array of mailbox strings. Entries should be valid email addresses with optional display names (for example, `Ada `).", "oneOf": [ { "type": "string", "description": "Single RFC 5322-style mailbox string." }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "cc": { "description": "Recipient field accepted as either one RFC 5322 mailbox string or an array of mailbox strings. Entries should be valid email addresses with optional display names (for example, `Ada `).", "oneOf": [ { "type": "string", "description": "Single RFC 5322-style mailbox string." }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "bcc": { "description": "Recipient field accepted as either one RFC 5322 mailbox string or an array of mailbox strings. Entries should be valid email addresses with optional display names (for example, `Ada `).", "oneOf": [ { "type": "string", "description": "Single RFC 5322-style mailbox string." }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string" }, "html": { "type": "string" }, "reply_to": { "type": "string" }, "headers": { "type": "object", "description": "Optional custom message headers. Values should be scalar JSON values.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "attachments": { "type": "array", "description": "Attachments for this email. The total JSON request body is limited to 15 MB (413 `payload_too_large`); base64 encoding adds ~33% overhead, so effective attachment content is roughly 11 MB per request. The same body limit applies to batch requests, shared across all items.", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "The filename shown to recipients." }, "content": { "type": "string", "description": "Base64-encoded attachment content." }, "encoding": { "type": "string", "description": "Encoding used for `content`. Use `base64` for public API requests.", "enum": [ "base64", "utf8", "ascii", "latin1", "hex" ] }, "content_type": { "type": "string", "description": "MIME type for the attachment." }, "content_id": { "type": "string", "description": "Optional Content-ID for inline attachments." } }, "required": [ "filename", "content" ], "additionalProperties": false } } }, "required": [ "from", "to", "subject" ], "anyOf": [ { "required": [ "text" ] }, { "required": [ "html" ] } ], "additionalProperties": false, "description": "A single send request. Unknown fields are rejected with a 400 `unknown_field` validation error." } } } } }, "get": { "summary": "List emails", "operationId": "listEmails", "responses": { "200": { "description": "Email page.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Email identifier in the `email_` format." }, "domain_id": { "type": [ "string", "null" ], "description": "Domain identifier in the `dom_` format for the sending domain used by this message." }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "recipient_type": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "description": "Email lifecycle status. `failed` means delivery failed with no remaining retries. `rejected` means the email was refused before or at acceptance (e.g., `suppressed_email` when the recipient is on the team suppression list). `bounced` means the receiving server returned the email after acceptance. `retry` means a prior attempt failed and another attempt is scheduled. `sent` means accepted by the upstream provider. `delivered` means provider-confirmed mailbox delivery.", "enum": [ "queued", "sending", "sent", "failed", "retry", "delivered", "bounced", "rejected" ] }, "rejection_code": { "type": [ "string", "null" ], "description": "Provider- or platform-level rejection code when status is `rejected` (e.g., `suppressed_email`)." }, "rejection_reason": { "type": [ "string", "null" ], "description": "Human-readable rejection reason when status is `rejected`." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the upstream provider accepted the message." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when provider delivery confirmation was received." }, "bounced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the receiving server returned the email after acceptance (status `bounced`)." }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the message was rejected by the provider." } }, "required": [ "id", "domain_id", "from", "to", "subject", "recipient_type", "status", "rejection_code", "rejection_reason", "sent_at", "delivered_at", "bounced_at", "rejected_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or `null` when there are no further results." } }, "required": [ "limit", "has_more", "next_cursor" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "example": { "data": [ { "id": "email_01kxh2fjhze009s9d337jd18jt", "domain_id": "dom_01kxjf1tyje00bgxb0s9g4gfxn", "from": "Ada Lovelace ", "to": "Grace Hopper ", "subject": "Welcome", "recipient_type": "to", "status": "delivered", "rejection_code": null, "rejection_reason": null, "sent_at": "2026-07-14T19:43:23.000Z", "delivered_at": "2026-07-14T19:43:25.000Z", "bounced_at": null, "rejected_at": null } ], "pagination": { "limit": 50, "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0xNFQxOTo0MzoyMy4wMDBaIiwicHVibGljX2lkIjoiZW1haWxfMDFreGgyZmpoemUwMDlzOWQzMzdqZDE4anQifQ" } } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_cursor", "message": "Invalid cursor", "retryable": false, "suggested_action": "fix_input" } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Lists emails for the authenticated API key’s team using cursor pagination. One email record exists per accepted recipient.", "tags": [ "Emails" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return. Values are clamped to the `1..100` range.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque base64url cursor returned by a previous list response. Pass the `next_cursor` value from the previous page to retrieve the next page.", "required": false, "schema": { "type": "string" }, "example": "eyJpZCI6ImFiYzEyMyJ9" }, { "name": "domain_id", "in": "query", "required": false, "description": "Optional domain identifier filter.", "schema": { "type": "string" }, "example": "dom_01jqnhcq36ebsv5sbvkxqhp79a" }, { "name": "status", "in": "query", "required": false, "description": "Optional message status filter.", "schema": { "type": "string", "description": "Email lifecycle status. `failed` means delivery failed with no remaining retries. `rejected` means the email was refused before or at acceptance (e.g., `suppressed_email` when the recipient is on the team suppression list). `bounced` means the receiving server returned the email after acceptance. `retry` means a prior attempt failed and another attempt is scheduled. `sent` means accepted by the upstream provider. `delivered` means provider-confirmed mailbox delivery.", "enum": [ "queued", "sending", "sent", "failed", "retry", "delivered", "bounced", "rejected" ] } } ] } }, "/v1/emails/batch": { "post": { "summary": "Send multiple emails in one request", "operationId": "sendEmailBatch", "responses": { "202": { "description": "Batch accepted.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "One inner array per item in the original batch request, each containing the accepted emails for that item.", "properties": { "emails": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Email identifier in the `email_` format." }, "to": { "type": "string", "format": "email", "description": "Normalized recipient address. Display names supplied in the request are stripped." } }, "required": [ "id", "to" ], "additionalProperties": false }, "minItems": 1 } } }, "required": [ "emails" ], "additionalProperties": false }, "example": { "emails": [ [ { "id": "email_01kxx24h94e00v5rgamqhe607z", "to": "ada@example.com" } ], [ { "id": "email_01kxx24hfpe00tqw50dqhgwbfe", "to": "grace@example.com" } ] ] } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "batch_validation_failed", "message": "One or more messages failed validation" }, "errors": [ { "index": 1, "errors": [ { "code": "missing_subject", "message": "subject is required", "field": "subject", "retryable": false, "suggested_action": "fix_input" } ] } ], "total": 2, "failed": 1 } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "402": { "description": "The authenticated team does not have enough credits for every accepted recipient in the request.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "insufficient_credits", "message": "Insufficient credit balance to send this email.", "retryable": false, "suggested_action": "top_up_credits", "available_credits": 0 } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "idempotency_key_conflict", "message": "Idempotency key already used with a different request body", "retryable": false, "suggested_action": "use_new_idempotency_key" } } } } }, "413": { "description": "Request body exceeds the maximum size.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "payload_too_large", "message": "Request body too large. Maximum size is 15MB", "retryable": false, "suggested_action": "fix_input" } } } } }, "415": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "A required service is temporarily unavailable, so the request could not be accepted for delivery. A `credit_check_failed` response means the current team credit balance could not be verified. Wait at least Retry-After and retry with exponential backoff using the same idempotency key and request body.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "credit_check_failed", "message": "Unable to verify credit balance. Please try again later.", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 2, "retry_strategy": "exponential_backoff" } } } } } }, "description": "Validates every item in the batch and accepts each email independently for asynchronous delivery. If validation fails for any item, the entire request is rejected before any emails are accepted. Maximum 1000 emails per request.", "tags": [ "Emails" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for send and batch-send requests. If a request with the same key was already accepted, the server returns the original accepted response without creating duplicate messages. Keys are scoped per API key and retained for 24 hours. Use a unique value per logical send operation (e.g., a UUID).", "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "RFC 5322-style sender address." }, "to": { "description": "Recipient field accepted as either one RFC 5322 mailbox string or an array of mailbox strings. Entries should be valid email addresses with optional display names (for example, `Ada `).", "oneOf": [ { "type": "string", "description": "Single RFC 5322-style mailbox string." }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "cc": { "description": "Recipient field accepted as either one RFC 5322 mailbox string or an array of mailbox strings. Entries should be valid email addresses with optional display names (for example, `Ada `).", "oneOf": [ { "type": "string", "description": "Single RFC 5322-style mailbox string." }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "bcc": { "description": "Recipient field accepted as either one RFC 5322 mailbox string or an array of mailbox strings. Entries should be valid email addresses with optional display names (for example, `Ada `).", "oneOf": [ { "type": "string", "description": "Single RFC 5322-style mailbox string." }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string" }, "html": { "type": "string" }, "reply_to": { "type": "string" }, "headers": { "type": "object", "description": "Optional custom message headers. Values should be scalar JSON values.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "attachments": { "type": "array", "description": "Attachments for this email. The total JSON request body is limited to 15 MB (413 `payload_too_large`); base64 encoding adds ~33% overhead, so effective attachment content is roughly 11 MB per request. The same body limit applies to batch requests, shared across all items.", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "The filename shown to recipients." }, "content": { "type": "string", "description": "Base64-encoded attachment content." }, "encoding": { "type": "string", "description": "Encoding used for `content`. Use `base64` for public API requests.", "enum": [ "base64", "utf8", "ascii", "latin1", "hex" ] }, "content_type": { "type": "string", "description": "MIME type for the attachment." }, "content_id": { "type": "string", "description": "Optional Content-ID for inline attachments." } }, "required": [ "filename", "content" ], "additionalProperties": false } } }, "required": [ "from", "to", "subject" ], "anyOf": [ { "required": [ "text" ] }, { "required": [ "html" ] } ], "additionalProperties": false, "description": "A single send request. Unknown fields are rejected with a 400 `unknown_field` validation error." }, "minItems": 1, "maxItems": 1000, "description": "Batch items; each item is validated and accepted independently." } }, "required": [ "emails" ], "additionalProperties": false } } } } } }, "/v1/emails/{email_id}": { "get": { "summary": "Get email", "operationId": "getEmail", "responses": { "200": { "description": "Email details.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Email identifier in the `email_` format." }, "domain_id": { "type": [ "string", "null" ], "description": "Domain identifier in the `dom_` format for the sending domain used by this message." }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "recipient_type": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "description": "Email lifecycle status. `failed` means delivery failed with no remaining retries. `rejected` means the email was refused before or at acceptance (e.g., `suppressed_email` when the recipient is on the team suppression list). `bounced` means the receiving server returned the email after acceptance. `retry` means a prior attempt failed and another attempt is scheduled. `sent` means accepted by the upstream provider. `delivered` means provider-confirmed mailbox delivery.", "enum": [ "queued", "sending", "sent", "failed", "retry", "delivered", "bounced", "rejected" ] }, "rejection_code": { "type": [ "string", "null" ], "description": "Provider- or platform-level rejection code when status is `rejected` (e.g., `suppressed_email`)." }, "rejection_reason": { "type": [ "string", "null" ], "description": "Human-readable rejection reason when status is `rejected`." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the upstream provider accepted the message." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when provider delivery confirmation was received." }, "bounced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the receiving server returned the email after acceptance (status `bounced`)." }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the message was rejected by the provider." } }, "required": [ "id", "domain_id", "from", "to", "subject", "recipient_type", "status", "rejection_code", "rejection_reason", "sent_at", "delivered_at", "bounced_at", "rejected_at" ], "additionalProperties": false } ] }, "example": { "id": "email_01kxh2fjhze009s9d337jd18jt", "domain_id": "dom_01kxjf1tyje00bgxb0s9g4gfxn", "from": "Ada Lovelace ", "to": "Grace Hopper ", "subject": "Welcome", "recipient_type": "to", "status": "delivered", "rejection_code": null, "rejection_reason": null, "sent_at": "2026-07-14T19:43:23.000Z", "delivered_at": "2026-07-14T19:43:25.000Z", "bounced_at": null, "rejected_at": null } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Email not found", "retryable": false } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Returns a single email owned by the authenticated API key’s team.", "tags": [ "Emails" ], "parameters": [ { "name": "email_id", "in": "path", "required": true, "description": "Email identifier in the `email_` format.", "schema": { "type": "string", "pattern": "^email_[0-9a-z]+$" }, "example": "email_01jz3fpxmxqj8w3xknnq3q50yk" } ] } }, "/v1/suppressions": { "get": { "summary": "List suppressions", "operationId": "listSuppressions", "responses": { "200": { "description": "Suppression page.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Suppression identifier in the `sup_` format." }, "email": { "type": "string", "format": "email" }, "type": { "type": [ "string", "null" ], "description": "Suppression source type (e.g., `manual`, `hard_bounce`, `complaint`). Null when the type is unknown or not recorded." }, "suppressed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "type", "suppressed_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or `null` when there are no further results." } }, "required": [ "limit", "has_more", "next_cursor" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "example": { "data": [ { "id": "sup_01jz3g2kkmrf6f60dteh4mft9n", "email": "user@example.com", "type": "manual", "suppressed_at": "2026-04-07T09:11:10Z" } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_cursor", "message": "Invalid cursor", "retryable": false, "suggested_action": "fix_input" } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Lists suppressions for the authenticated API key’s team, optionally filtering by exact email.", "tags": [ "Suppressions" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return. Values are clamped to the `1..100` range.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque base64url cursor returned by a previous list response. Pass the `next_cursor` value from the previous page to retrieve the next page.", "required": false, "schema": { "type": "string" }, "example": "eyJpZCI6ImFiYzEyMyJ9" }, { "name": "email", "in": "query", "required": false, "description": "Exact-match suppression email filter. The server normalizes input to lowercase before matching.", "schema": { "type": "string", "format": "email" } } ] }, "post": { "summary": "Create a suppression", "operationId": "createSuppression", "responses": { "201": { "description": "Suppression created.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Suppression identifier in the `sup_` format." }, "email": { "type": "string", "format": "email" }, "type": { "type": [ "string", "null" ], "description": "Suppression source type (e.g., `manual`, `hard_bounce`, `complaint`). Null when the type is unknown or not recorded." }, "suppressed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "type", "suppressed_at" ], "additionalProperties": false } ] }, "example": { "id": "sup_01jz3g2kkmrf6f60dteh4mft9n", "email": "user@example.com", "type": "manual", "suppressed_at": "2026-04-07T09:11:10Z" } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "suppression_exists", "message": "Suppression already exists" }, "errors": [ { "code": "suppression_exists", "message": "Suppression already exists", "field": "email", "value": "user@example.com", "retryable": false, "suggested_action": "fix_input" } ] } } } }, "413": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Creates a manual suppression for the authenticated API key’s team.", "tags": [ "Suppressions" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "examples": [ "user@example.com" ] } }, "required": [ "email" ], "additionalProperties": false, "examples": [ { "email": "user@example.com" } ] }, "example": { "email": "user@example.com" } } } } } }, "/v1/suppressions/{suppression_id_or_email}": { "get": { "summary": "Get suppression", "operationId": "getSuppression", "responses": { "200": { "description": "Suppression details.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Suppression identifier in the `sup_` format." }, "email": { "type": "string", "format": "email" }, "type": { "type": [ "string", "null" ], "description": "Suppression source type (e.g., `manual`, `hard_bounce`, `complaint`). Null when the type is unknown or not recorded." }, "suppressed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "type", "suppressed_at" ], "additionalProperties": false } ] }, "example": { "id": "sup_01jz3g2kkmrf6f60dteh4mft9n", "email": "user@example.com", "type": "manual", "suppressed_at": "2026-07-15T08:51:37.000Z" } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Suppression not found", "retryable": false } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Returns a single suppression owned by the authenticated API key’s team, addressed by suppression ID or by suppressed email address.", "tags": [ "Suppressions" ], "parameters": [ { "name": "suppression_id_or_email", "in": "path", "required": true, "description": "Suppression identifier in the `sup_` format, or the suppressed email address. Values matching `^sup_[0-9a-z]+$` are treated as IDs; anything else is treated as an email address and matched exactly after lowercasing. Percent-encode special characters in emails (`@` as `%40`, `+` as `%2B`). Examples: `sup_01jz3g2kkmrf6f60dteh4mft9n` or `user%40example.com`.", "schema": { "type": "string" }, "example": "sup_01jz3g2kkmrf6f60dteh4mft9n" } ] }, "delete": { "summary": "Delete a suppression", "operationId": "deleteSuppression", "responses": { "204": { "description": "Suppression deleted.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Suppression not found", "retryable": false } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Soft deletes a suppression owned by the authenticated API key’s team, addressed by suppression ID or by suppressed email address. Deleting a suppression only affects future sends and does not alter historic email state.", "tags": [ "Suppressions" ], "parameters": [ { "name": "suppression_id_or_email", "in": "path", "required": true, "description": "Suppression identifier in the `sup_` format, or the suppressed email address. Values matching `^sup_[0-9a-z]+$` are treated as IDs; anything else is treated as an email address and matched exactly after lowercasing. Percent-encode special characters in emails (`@` as `%40`, `+` as `%2B`). Examples: `sup_01jz3g2kkmrf6f60dteh4mft9n` or `user%40example.com`.", "schema": { "type": "string" }, "example": "sup_01jz3g2kkmrf6f60dteh4mft9n" } ] } }, "/v1/domains": { "get": { "summary": "List domains", "operationId": "listDomains", "responses": { "200": { "description": "Domain page.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Domain identifier in the `dom_` format." }, "domain": { "type": "string", "description": "The ICANN domain name." }, "is_verified": { "type": "boolean", "description": "Whether all required DNS records have been verified." }, "is_disabled": { "type": "boolean", "description": "Whether the domain has been disabled. Disabled domains cannot send email." }, "disabled_reason": { "type": [ "string", "null" ], "description": "Human-readable reason the domain was disabled, or `null` if not disabled." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the domain was created." } }, "required": [ "id", "domain", "is_verified", "is_disabled", "disabled_reason", "created_at" ] } ], "unevaluatedProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or `null` when there are no further results." } }, "required": [ "limit", "has_more", "next_cursor" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "example": { "data": [ { "id": "dom_01jqnhcq36ebsv5sbvkxqhp79a", "domain": "mg.prontuno.com", "is_verified": true, "is_disabled": false, "disabled_reason": null, "created_at": "2026-04-07T07:00:00Z" } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_cursor", "message": "Invalid cursor", "retryable": false, "suggested_action": "fix_input" } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Lists domains owned by the authenticated API key’s team with cursor pagination.", "tags": [ "Domains" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return. Values are clamped to the `1..100` range.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque base64url cursor returned by a previous list response. Pass the `next_cursor` value from the previous page to retrieve the next page.", "required": false, "schema": { "type": "string" }, "example": "eyJpZCI6ImFiYzEyMyJ9" } ] }, "post": { "summary": "Create a sending domain", "operationId": "createDomain", "responses": { "201": { "description": "Domain created.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Domain identifier in the `dom_` format." }, "domain": { "type": "string", "description": "The ICANN domain name." }, "is_verified": { "type": "boolean", "description": "Whether all required DNS records have been verified." }, "is_disabled": { "type": "boolean", "description": "Whether the domain has been disabled. Disabled domains cannot send email." }, "disabled_reason": { "type": [ "string", "null" ], "description": "Human-readable reason the domain was disabled, or `null` if not disabled." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the domain was created." } }, "required": [ "id", "domain", "is_verified", "is_disabled", "disabled_reason", "created_at" ] }, { "type": "object", "properties": { "dns_records": { "type": "array", "description": "Typically includes verification and sending DNS records such as SPF, DKIM, and related records.", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "verified" ] }, "record_type": { "type": "string", "enum": [ "CNAME", "TXT" ] }, "hostname": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "integer" } }, "required": [ "status", "record_type", "hostname", "value", "ttl" ], "additionalProperties": false } } }, "required": [ "dns_records" ] } ], "unevaluatedProperties": false }, "example": { "id": "dom_01kxjf1tyje00bgxb0s9g4gfxn", "domain": "mg.example.com", "is_verified": false, "is_disabled": false, "disabled_reason": null, "created_at": "2026-07-15T08:42:18.000Z", "dns_records": [ { "status": "pending", "record_type": "CNAME", "hostname": "pno1234.mg.example.com", "value": "out.prontuno.net", "ttl": 86400 }, { "status": "pending", "record_type": "CNAME", "hostname": "prontuno1._domainkey.pno1234.mg.example.com", "value": "prontuno1.pno1234.dkim.prontuno.net", "ttl": 86400 }, { "status": "pending", "record_type": "CNAME", "hostname": "prontuno2._domainkey.pno1234.mg.example.com", "value": "prontuno2.pno1234.dkim.prontuno.net", "ttl": 86400 }, { "status": "pending", "record_type": "TXT", "hostname": "_dmarc.mg.example.com", "value": "v=DMARC1; p=none;", "ttl": 86400 } ] } } } }, "400": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Creates a domain for the authenticated API key’s team and returns the DNS records required for verification.", "tags": [ "Domains" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Fully qualified domain name to add u2014 an apex domain (`example.com`) or a subdomain (`mg.example.com`). Must use a public ICANN TLD (internal TLDs such as `.local` are rejected with `invalid_domain`). The server normalizes to lowercase; re-adding an existing domain in any case returns 409 `domain_exists`.", "examples": [ "mg.example.com" ] } }, "required": [ "domain" ], "additionalProperties": false, "examples": [ { "domain": "mg.example.com" } ] }, "example": { "domain": "mg.example.com" } } } } } }, "/v1/domains/{domain_id}": { "get": { "summary": "Get domain", "operationId": "getDomain", "responses": { "200": { "description": "Domain details.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Domain identifier in the `dom_` format." }, "domain": { "type": "string", "description": "The ICANN domain name." }, "is_verified": { "type": "boolean", "description": "Whether all required DNS records have been verified." }, "is_disabled": { "type": "boolean", "description": "Whether the domain has been disabled. Disabled domains cannot send email." }, "disabled_reason": { "type": [ "string", "null" ], "description": "Human-readable reason the domain was disabled, or `null` if not disabled." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the domain was created." } }, "required": [ "id", "domain", "is_verified", "is_disabled", "disabled_reason", "created_at" ] }, { "type": "object", "properties": { "dns_records": { "type": "array", "description": "Typically includes verification and sending DNS records such as SPF, DKIM, and related records.", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "verified" ] }, "record_type": { "type": "string", "enum": [ "CNAME", "TXT" ] }, "hostname": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "integer" } }, "required": [ "status", "record_type", "hostname", "value", "ttl" ], "additionalProperties": false } } }, "required": [ "dns_records" ] } ], "unevaluatedProperties": false }, "example": { "id": "dom_01kxjf1tyje00bgxb0s9g4gfxn", "domain": "mg.example.com", "is_verified": false, "is_disabled": false, "disabled_reason": null, "created_at": "2026-07-15T08:42:18.000Z", "dns_records": [ { "status": "pending", "record_type": "CNAME", "hostname": "pno1234.mg.example.com", "value": "out.prontuno.net", "ttl": 86400 }, { "status": "pending", "record_type": "CNAME", "hostname": "prontuno1._domainkey.pno1234.mg.example.com", "value": "prontuno1.pno1234.dkim.prontuno.net", "ttl": 86400 }, { "status": "pending", "record_type": "CNAME", "hostname": "prontuno2._domainkey.pno1234.mg.example.com", "value": "prontuno2.pno1234.dkim.prontuno.net", "ttl": 86400 }, { "status": "pending", "record_type": "TXT", "hostname": "_dmarc.mg.example.com", "value": "v=DMARC1; p=none;", "ttl": 86400 } ] } } } }, "401": { "description": "Missing, invalid, disabled, expired, or teamless public API key.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Authentication challenge; the server returns `Bearer`." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key", "retryable": false, "suggested_action": "fix_input" } } } } }, "403": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Domain not found", "retryable": false } } } } }, "429": { "description": "Rate limit exceeded. Use the `RateLimit-*` headers and `Retry-After` (seconds) for retry timing.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Maximum number of requests allowed for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Number of requests remaining for the team in the current rate limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retryable": true, "suggested_action": "retry_later", "retry_after_seconds": 1 } } } } }, "500": { "description": "Structured error response.", "headers": { "x-request-id": { "description": "Request correlation identifier generated or echoed by the server.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "available_credits": { "type": "integer", "minimum": 0, "description": "Current team credit balance, returned with `insufficient_credits`." }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ], "additionalProperties": false }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "value": [], "path": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether the client may retry this request. `true` for transient errors (e.g., 500, 503). `false` for permanent failures such as validation errors, invalid API keys, or quota exhaustion." }, "suggested_action": { "type": "string", "description": "Suggested client next step for resolving the error.", "enum": [ "fix_input", "retry_later", "contact_support", "reauthenticate", "check_permissions", "check_server_configuration", "check_endpoint", "use_new_idempotency_key", "top_up_credits" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "retry_strategy": { "type": "string", "enum": [ "exponential_backoff" ] }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "index", "errors" ], "additionalProperties": false } ] }, "minItems": 1 }, "total": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Returns a single domain owned by the authenticated API key’s team, including DNS verification records.", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Domain identifier in the `dom_` format.", "schema": { "type": "string", "pattern": "^dom_[0-9a-z]+$" }, "example": "dom_01jqnhcq36ebsv5sbvkxqhp79a" } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "security": [ { "BearerAuth": [] } ] }