{ "openapi": "3.1.2", "info": { "title": "Resend", "version": "1.5.1", "description": "Resend is the email platform for developers." }, "servers": [ { "url": "https://api.resend.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Emails", "description": "Start sending emails through the Resend API." }, { "name": "Domains", "description": "Create and manage domains through the Resend API." }, { "name": "API Keys", "description": "Create and manage API Keys through the Resend API." }, { "name": "Audiences", "description": "Deprecated: Use Segments instead. Create and manage Audiences through the Resend API." }, { "name": "Contacts", "description": "Create and manage Contacts through the Resend API." }, { "name": "Receiving Emails", "description": "Retrieve and manage received emails and attachments through the Resend API." }, { "name": "Webhooks", "description": "Create and manage Webhooks through the Resend API." }, { "name": "Webhook Events", "description": "Real-time event notifications delivered to your registered webhook endpoint. Each delivery is signed using Svix headers (`svix-id`, `svix-timestamp`, `svix-signature`); verify them before acting on the payload." }, { "name": "Templates", "description": "Create and manage Templates through the Resend API." }, { "name": "Broadcasts", "description": "Create and manage Broadcasts through the Resend API." }, { "name": "Segments", "description": "Create and manage Segments through the Resend API." }, { "name": "Topics", "description": "Create and manage Topics through the Resend API." }, { "name": "Contact Properties", "description": "Create and manage Contact Properties through the Resend API." }, { "name": "Suppressions", "description": "Create and manage Suppressions through the Resend API." }, { "name": "Logs", "description": "Retrieve API request logs through the Resend API." }, { "name": "Automations", "description": "Create and manage Automations through the Resend API." }, { "name": "Events", "description": "Create and manage Events through the Resend API." }, { "name": "OAuth", "description": "List and manage OAuth grants through the Resend API." }, { "name": "Usage", "description": "Retrieve your account usage and plan limits through the Resend API." }, { "name": "Inboxes", "description": "Create and manage Inboxes through the Resend API. A sending access key can call only these Inboxes endpoints: `POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/reply`, `POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/forward`, `POST /inboxes/{inbox_id}/drafts` and `POST /inboxes/{inbox_id}/drafts/{draft_id}/send`. When the key is limited to one domain, the inbox address must be on that domain, or the request returns a 403. Every other Inboxes endpoint needs a full access API key, and a sending access key returns a 401 `restricted_api_key`." } ], "paths": { "/emails": { "post": { "operationId": "emails/send", "tags": [ "Emails" ], "summary": "Send an email", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "A unique identifier for the request to ensure emails are only sent once. [Learn more](https://resend.com/docs/dashboard/emails/idempotency-keys)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponse" } } } } } }, "get": { "operationId": "emails/list", "tags": [ "Emails" ], "summary": "Retrieve a list of emails", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmailsResponse" } } } } } } }, "/emails/{email_id}": { "get": { "operationId": "emails/get", "tags": [ "Emails" ], "summary": "Retrieve a single email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the email." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } } } }, "patch": { "operationId": "emails/update", "tags": [ "Emails" ], "summary": "Update a single email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the email." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailOptions" } } } } } } }, "/emails/{email_id}/cancel": { "post": { "operationId": "emails/cancel", "tags": [ "Emails" ], "summary": "Cancel the schedule of the e-mail.", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the email." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } } } } }, "/emails/{email_id}/share": { "post": { "operationId": "emails/share", "tags": [ "Emails" ], "summary": "Create a shareable link for a sent or received email.", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the email." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareEmailOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareEmailResponse" } } } } } } }, "/emails/batch": { "post": { "operationId": "emails/send-batch", "tags": [ "Emails" ], "summary": "Trigger up to 100 batch emails at once.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "A unique identifier for the request to ensure emails are only sent once. [Learn more](https://resend.com/docs/dashboard/emails/idempotency-keys)" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SendEmailRequest" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBatchEmailsResponse" } } } } } } }, "/emails/{email_id}/attachments": { "get": { "operationId": "emails/list-attachments", "tags": [ "Emails" ], "summary": "Retrieve a list of attachments for a sent email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the email." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of attachments to return." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results after this attachment ID. Cannot be used with 'before'." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results before this attachment ID. Cannot be used with 'after'." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAttachmentsResponse" } } } } } } }, "/emails/{email_id}/attachments/{attachment_id}": { "get": { "operationId": "emails/get-attachment", "tags": [ "Emails" ], "summary": "Retrieve a single attachment for a sent email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the email." }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the attachment." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievedAttachment" } } } } } } }, "/emails/receiving": { "get": { "operationId": "emails/list-receiving", "tags": [ "Receiving Emails" ], "summary": "Retrieve a list of received emails", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of received emails to return." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results after this email ID. Cannot be used with 'before'." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results before this email ID. Cannot be used with 'after'." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReceivedEmailsResponse" } } } } } } }, "/emails/receiving/{email_id}": { "get": { "operationId": "emails/get-receiving", "tags": [ "Receiving Emails" ], "summary": "Retrieve a single received email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the received email." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReceivedEmailResponse" } } } } } } }, "/emails/receiving/{email_id}/attachments": { "get": { "operationId": "emails/list-receiving-attachments", "tags": [ "Receiving Emails" ], "summary": "Retrieve a list of attachments for a received email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the received email." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of attachments to return." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results after this attachment ID. Cannot be used with 'before'." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results before this attachment ID. Cannot be used with 'after'." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAttachmentsResponse" } } } } } } }, "/emails/receiving/{email_id}/attachments/{attachment_id}": { "get": { "operationId": "emails/get-receiving-attachment", "tags": [ "Receiving Emails" ], "summary": "Retrieve a single attachment for a received email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the received email." }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the attachment." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievedAttachment" } } } } } } }, "/emails/metrics": { "get": { "operationId": "emails/metrics", "tags": [ "Emails" ], "summary": "Retrieve account-level email metrics", "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "The start of the date range, as an ISO 8601 date or datetime. Must be on or before `end_date`. Defaults to 6 days before `end_date`." }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "The end of the date range, as an ISO 8601 date or datetime. Values in the future are clamped to the current time. Defaults to now." }, { "name": "timezone", "in": "query", "schema": { "type": "string", "default": "UTC" }, "description": "The IANA timezone (e.g. `America/New_York`) used to bucket periods when `period` is in `dimensions`." }, { "name": "granularity", "in": "query", "schema": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly" ], "default": "daily" }, "description": "The bucket size used when `period` is in `dimensions`. The date range can't produce more than 10,000 periods at the chosen granularity." }, { "name": "metrics", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "received", "delivered", "complained", "suppressed", "bounced", "bounced_transient", "bounced_permanent", "bounced_undetermined", "opened", "clicked", "unsubscribed", "delivery_delayed", "failed", "sent", "unique_opened", "unique_clicked", "delivery_rate", "open_rate", "click_rate", "bounce_rate", "complaint_rate", "unsubscribe_rate" ] } }, "description": "List of metrics to include in the response. Defaults to all metrics. Accepts a comma-separated value, the parameter repeated, or a mix of both." }, { "name": "dimensions", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "period", "domain", "email", "broadcast" ] } }, "description": "List of dimensions to break the response down by. `email` cannot be combined with `broadcast`. Defaults to `[]`, returning a single `totals` row for the whole range, with no `data`. Accepts a comma-separated value, the parameter repeated, or a mix of both." }, { "name": "domain_id", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "List of sending domain IDs to restrict the response to, up to 100. Accepts a comma-separated value, the parameter repeated, or a mix of both." }, { "name": "email_id", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "List of email IDs to restrict the response to, up to 100. Cannot be combined with the `broadcast` dimension or `broadcast_id`. Accepts a comma-separated value, the parameter repeated, or a mix of both." }, { "name": "broadcast_id", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": "List of broadcast IDs to restrict the response to, up to 100. Cannot be combined with the `email` dimension or `email_id`. Accepts a comma-separated value, the parameter repeated, or a mix of both." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEmailsMetricsResponse" } } } } } } }, "/domains": { "post": { "operationId": "domains/create", "tags": [ "Domains" ], "summary": "Create a new domain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainResponse" } } } } } }, "get": { "operationId": "domains/list", "tags": [ "Domains" ], "summary": "Retrieve a list of domains", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsResponse" } } } } } } }, "/domains/{domain_id}": { "get": { "operationId": "domains/get", "tags": [ "Domains" ], "summary": "Retrieve a single domain", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the domain." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } }, "patch": { "operationId": "domains/update", "tags": [ "Domains" ], "summary": "Update an existing domain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDomainOptions" } } } }, "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the domain." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDomainResponseSuccess" } } } } } }, "delete": { "operationId": "domains/remove", "tags": [ "Domains" ], "summary": "Remove an existing domain", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the domain." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDomainResponse" } } } } } } }, "/domains/{domain_id}/verify": { "post": { "operationId": "domains/verify", "tags": [ "Domains" ], "summary": "Verify an existing domain", "description": "Triggers verification of the domain's DNS records including DKIM, SPF, and the tracking CNAME (if a tracking subdomain is configured).", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the domain." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDomainResponse" } } } } } } }, "/domains/claim": { "post": { "operationId": "domains/create-claim", "tags": [ "Domains" ], "summary": "Claim a domain", "description": "Start a claim for a domain that another Resend account has already verified. The domain is recreated under your account with fresh DKIM keys, so the previous account's DNS records cannot be reused. Returns a TXT record to add to your DNS to prove ownership. Uses the same request body as creating a domain.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainClaimRequest" } } } }, "responses": { "201": { "description": "Claim created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainClaim" } } } }, "200": { "description": "An identical pending claim already existed and was returned unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainClaim" } } } } } } }, "/domains/{domain_id}/claim": { "get": { "operationId": "domains/get-claim", "tags": [ "Domains" ], "summary": "Retrieve a domain claim", "description": "Retrieve the latest claim for the placeholder domain created by the claim.", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the placeholder domain created by the claim." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainClaim" } } } } } } }, "/domains/{domain_id}/claim/verify": { "post": { "operationId": "domains/verify-claim", "tags": [ "Domains" ], "summary": "Verify a domain claim", "description": "Trigger asynchronous DNS verification and ownership transfer for a domain claim. The claim stays `pending` while verification runs; poll the retrieve endpoint for status. Once `completed`, the transferred domain has new DKIM records that must be added to DNS and verified via the standard domain verify endpoint.", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the placeholder domain created by the claim." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainClaim" } } } } } } }, "/api-keys": { "post": { "operationId": "api-keys/create", "tags": [ "API Keys" ], "summary": "Create a new API key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } } } }, "get": { "operationId": "api-keys/list", "tags": [ "API Keys" ], "summary": "Retrieve a list of API keys", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } } } } }, "/api-keys/{api_key_id}": { "patch": { "operationId": "api-keys/update", "tags": [ "API Keys" ], "summary": "Update an existing API key", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The API key ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyResponse" } } } } } }, "delete": { "operationId": "api-keys/remove", "tags": [ "API Keys" ], "summary": "Remove an existing API key", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The API key ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyResponse" } } } } } } }, "/oauth/grants": { "get": { "operationId": "oauth/list-grants", "tags": [ "OAuth" ], "summary": "Retrieve a list of OAuth grants", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOAuthGrantsResponse" } } } } } } }, "/oauth/grants/{oauth_grant_id}": { "delete": { "operationId": "oauth/revoke-grant", "tags": [ "OAuth" ], "summary": "Revoke an OAuth grant", "parameters": [ { "name": "oauth_grant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The OAuth grant ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeOAuthGrantResponse" } } } } } } }, "/templates": { "post": { "operationId": "templates/create", "tags": [ "Templates" ], "summary": "Create a template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateResponseSuccess" } } } } } }, "get": { "operationId": "templates/list", "tags": [ "Templates" ], "summary": "Retrieve a list of templates", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponseSuccess" } } } } } } }, "/templates/{id}": { "get": { "operationId": "templates/get", "tags": [ "Templates" ], "summary": "Retrieve a single template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } } } }, "patch": { "operationId": "templates/update", "tags": [ "Templates" ], "summary": "Update an existing template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Template ID or alias." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateResponseSuccess" } } } } } }, "delete": { "operationId": "templates/remove", "tags": [ "Templates" ], "summary": "Remove an existing template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTemplateResponseSuccess" } } } } } } }, "/templates/{id}/publish": { "post": { "operationId": "templates/publish", "tags": [ "Templates" ], "summary": "Publish a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishTemplateResponseSuccess" } } } } } } }, "/templates/{id}/duplicate": { "post": { "operationId": "templates/duplicate", "tags": [ "Templates" ], "summary": "Duplicate a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTemplateResponseSuccess" } } } } } } }, "/audiences": { "post": { "operationId": "audiences/create", "tags": [ "Audiences" ], "summary": "Create a list of contacts", "deprecated": true, "description": "Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceResponseSuccess" } } } } } }, "get": { "operationId": "audiences/list", "tags": [ "Audiences" ], "summary": "Retrieve a list of audiences", "deprecated": true, "description": "Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAudiencesResponseSuccess" } } } } } } }, "/audiences/{id}": { "delete": { "operationId": "audiences/remove", "tags": [ "Audiences" ], "summary": "Remove an existing audience", "deprecated": true, "description": "Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Audience ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAudienceResponseSuccess" } } } } } }, "get": { "operationId": "audiences/get", "tags": [ "Audiences" ], "summary": "Retrieve a single audience", "deprecated": true, "description": "Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Audience ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAudienceResponseSuccess" } } } } } } }, "/contacts": { "post": { "operationId": "contacts/create", "tags": [ "Contacts" ], "summary": "Create a new contact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactResponseSuccess" } } } } } }, "get": { "operationId": "contacts/list", "tags": [ "Contacts" ], "summary": "Retrieve a list of contacts", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsResponseSuccess" } } } } } } }, "/contacts/imports": { "post": { "operationId": "contacts/create-import", "tags": [ "Contacts" ], "summary": "Create a contact import", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateContactImportOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactImportResponseSuccess" } } } } } }, "get": { "operationId": "contacts/list-imports", "tags": [ "Contacts" ], "summary": "Retrieve a list of contact imports", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ] }, "description": "Filter contact imports by status." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactImportsResponseSuccess" } } } } } } }, "/contacts/imports/{id}": { "get": { "operationId": "contacts/get-import", "tags": [ "Contacts" ], "summary": "Retrieve a single contact import", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Contact Import ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactImportResponseSuccess" } } } } } } }, "/contacts/{id}": { "get": { "operationId": "contacts/get", "tags": [ "Contacts" ], "summary": "Retrieve a single contact by ID or email", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactResponseSuccess" } } } } } }, "patch": { "operationId": "contacts/update", "tags": [ "Contacts" ], "summary": "Update a single contact by ID or email", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactResponseSuccess" } } } } } }, "delete": { "operationId": "contacts/remove", "tags": [ "Contacts" ], "summary": "Remove an existing contact by ID or email", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactResponseSuccess" } } } } } } }, "/broadcasts": { "post": { "operationId": "broadcasts/create", "tags": [ "Broadcasts" ], "summary": "Create a broadcast", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBroadcastOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBroadcastResponseSuccess" } } } } } }, "get": { "operationId": "broadcasts/list", "tags": [ "Broadcasts" ], "summary": "Retrieve a list of broadcasts", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBroadcastsResponseSuccess" } } } } } } }, "/broadcasts/{id}": { "delete": { "operationId": "broadcasts/remove", "tags": [ "Broadcasts" ], "summary": "Remove an existing broadcast that is in the draft status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Broadcast ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveBroadcastResponseSuccess" } } } } } }, "get": { "operationId": "broadcasts/get", "tags": [ "Broadcasts" ], "summary": "Retrieve a single broadcast", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Broadcast ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBroadcastResponseSuccess" } } } } } }, "patch": { "operationId": "broadcasts/update", "tags": [ "Broadcasts" ], "summary": "Update an existing broadcast", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Broadcast ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBroadcastOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBroadcastResponseSuccess" } } } } } } }, "/broadcasts/{id}/send": { "post": { "operationId": "broadcasts/send", "tags": [ "Broadcasts" ], "summary": "Send or schedule a broadcast", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Broadcast ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBroadcastOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBroadcastResponseSuccess" } } } } } } }, "/broadcasts/{id}/cancel": { "post": { "operationId": "broadcasts/cancel", "tags": [ "Broadcasts" ], "summary": "Cancel a broadcast", "description": "Cancels a broadcast that is queued or scheduled. Canceling a queued broadcast stops it mid-send; emails already sent are not affected, but no further emails will go out.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Broadcast ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBroadcastResponseSuccess" } } } } } } }, "/broadcasts/{id}/duplicate": { "post": { "operationId": "broadcasts/duplicate", "tags": [ "Broadcasts" ], "summary": "Duplicate a broadcast", "description": "Creates a new draft broadcast with the same segment, topic, sender, subject, reply-to, preview text, and content as the source. The copy is named after the source with \" (copy)\" appended, truncated to 70 characters.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Broadcast ID." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateBroadcastResponseSuccess" } } } } } } }, "/broadcasts/{id}/recipients": { "get": { "operationId": "broadcasts/recipients", "tags": [ "Broadcasts" ], "summary": "Retrieve broadcast recipients", "description": "Retrieve the recipients of a broadcast for a given event type, such as who opened, clicked, or bounced.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Broadcast ID." }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "suppressed" ] }, "description": "The recipient event type to filter by." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter recipients whose email address contains this value." }, { "name": "bounce_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "permanent", "transient", "undetermined" ] }, "description": "Filter bounced recipients by bounce type. Only valid when `type` is `bounced`." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBroadcastRecipientsResponseSuccess" } } } } } } }, "/broadcasts/{id}/clicked-links": { "get": { "operationId": "broadcasts/list-clicked-links", "tags": [ "Broadcasts" ], "summary": "Retrieve a broadcast's clicked links", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Broadcast ID." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBroadcastClickedLinksResponseSuccess" } } } } } } }, "/webhooks": { "post": { "operationId": "webhooks/create", "tags": [ "Webhooks" ], "summary": "Create a new webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookResponse" } } } } } }, "get": { "operationId": "webhooks/list", "tags": [ "Webhooks" ], "summary": "Retrieve a list of webhooks", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of webhooks to return." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results after this webhook ID. Cannot be used with 'before'." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results before this webhook ID. Cannot be used with 'after'." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } } } } } }, "/webhooks/{webhook_id}": { "get": { "operationId": "webhooks/get", "tags": [ "Webhooks" ], "summary": "Retrieve a single webhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebhookResponse" } } } } } }, "patch": { "operationId": "webhooks/update", "tags": [ "Webhooks" ], "summary": "Update an existing webhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookResponse" } } } } } }, "delete": { "operationId": "webhooks/remove", "tags": [ "Webhooks" ], "summary": "Remove an existing webhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookResponse" } } } } } } }, "/webhooks/{webhook_id}/signing-secret/rotate": { "post": { "operationId": "webhooks/rotate-signing-secret", "tags": [ "Webhooks" ], "summary": "Rotate a webhook signing secret", "description": "Generates a new signing secret for the webhook and returns it. Payloads delivered after the rotation are signed with the new secret. The previous secret keeps verifying payloads for 24 hours, so both secrets are accepted during that window. A webhook that does not exist or was removed returns a 404 not_found.", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateWebhookSigningSecretResponse" } } } } } } }, "/webhooks/{webhook_id}/events": { "get": { "operationId": "webhooks/list-events", "tags": [ "Webhooks" ], "summary": "Retrieve a list of webhook events", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookEventsResponse" } } } } } } }, "/webhooks/{webhook_id}/events/{event_id}": { "get": { "operationId": "webhooks/get-event", "tags": [ "Webhooks" ], "summary": "Retrieve a single webhook event", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Webhook Event ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebhookEventResponse" } } } } } } }, "/webhooks/{webhook_id}/events/{event_id}/replay": { "post": { "operationId": "webhooks/replay-event", "tags": [ "Webhooks" ], "summary": "Replay a webhook event", "description": "Queues one more delivery of the event to the webhook. The event must be retrievable through the get event endpoint and the webhook must be enabled; a disabled webhook returns a 422 validation_error. A manual replay does not schedule automatic retries.", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Webhook Event ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayWebhookEventResponse" } } } } } } }, "/webhooks/{webhook_id}/events/{event_id}/attempts": { "get": { "operationId": "webhooks/list-event-attempts", "tags": [ "Webhooks" ], "summary": "Retrieve a list of webhook event attempts", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Webhook ID." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Webhook Event ID." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookEventAttemptsResponse" } } } } } } }, "/segments": { "post": { "operationId": "segments/create", "tags": [ "Segments" ], "summary": "Create a new segment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentResponseSuccess" } } } } } }, "get": { "operationId": "segments/list", "tags": [ "Segments" ], "summary": "Retrieve a list of segments", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSegmentsResponseSuccess" } } } } } } }, "/segments/{id}": { "get": { "operationId": "segments/get", "tags": [ "Segments" ], "summary": "Retrieve a single segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSegmentResponseSuccess" } } } } } }, "patch": { "operationId": "segments/update", "tags": [ "Segments" ], "summary": "Update an existing segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentResponseSuccess" } } } } } }, "delete": { "operationId": "segments/remove", "tags": [ "Segments" ], "summary": "Remove an existing segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSegmentResponseSuccess" } } } } } } }, "/segments/{id}/contacts": { "get": { "operationId": "segments/list-contacts", "tags": [ "Segments" ], "summary": "Retrieve a list of contacts in a segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Segment ID." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsResponseSuccess" } } } } } } }, "/topics": { "post": { "operationId": "topics/create", "tags": [ "Topics" ], "summary": "Create a new topic", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicResponseSuccess" } } } } } }, "get": { "operationId": "topics/list", "tags": [ "Topics" ], "summary": "Retrieve a list of topics", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTopicsResponseSuccess" } } } } } } }, "/topics/{id}": { "get": { "operationId": "topics/get", "tags": [ "Topics" ], "summary": "Retrieve a single topic", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Topic ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTopicResponseSuccess" } } } } } }, "patch": { "operationId": "topics/update", "tags": [ "Topics" ], "summary": "Update an existing topic", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Topic ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicResponseSuccess" } } } } } }, "delete": { "operationId": "topics/remove", "tags": [ "Topics" ], "summary": "Remove an existing topic", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Topic ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTopicResponseSuccess" } } } } } } }, "/contact-properties": { "post": { "operationId": "contact-properties/create", "tags": [ "Contact Properties" ], "summary": "Create a new contact property", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactPropertyOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactPropertyResponseSuccess" } } } } } }, "get": { "operationId": "contact-properties/list", "tags": [ "Contact Properties" ], "summary": "Retrieve a list of contact properties", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactPropertiesResponseSuccess" } } } } } } }, "/contact-properties/{id}": { "get": { "operationId": "contact-properties/get", "tags": [ "Contact Properties" ], "summary": "Retrieve a single contact property", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact Property ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactPropertyResponseSuccess" } } } } } }, "patch": { "operationId": "contact-properties/update", "tags": [ "Contact Properties" ], "summary": "Update an existing contact property", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact Property ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactPropertyOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactPropertyResponseSuccess" } } } } } }, "delete": { "operationId": "contact-properties/remove", "tags": [ "Contact Properties" ], "summary": "Remove an existing contact property", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact Property ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactPropertyResponseSuccess" } } } } } } }, "/contacts/{contact_id}/segments": { "get": { "operationId": "contacts/list-segments", "tags": [ "Contacts" ], "summary": "Retrieve a list of segments for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactSegmentsResponseSuccess" } } } } } } }, "/contacts/{contact_id}/segments/{segment_id}": { "post": { "operationId": "contacts/add-segment", "tags": [ "Contacts" ], "summary": "Add a contact to a segment", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContactToSegmentResponseSuccess" } } } } } }, "delete": { "operationId": "contacts/remove-segment", "tags": [ "Contacts" ], "summary": "Remove a contact from a segment", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactFromSegmentResponseSuccess" } } } } } } }, "/contacts/{contact_id}/topics": { "get": { "operationId": "contacts/list-topics", "tags": [ "Contacts" ], "summary": "Retrieve topics for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactTopicsResponseSuccess" } } } } } }, "patch": { "operationId": "contacts/update-topics", "tags": [ "Contacts" ], "summary": "Update topics for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactTopicsOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactTopicsResponseSuccess" } } } } } } }, "/logs": { "get": { "operationId": "logs/list", "tags": [ "Logs" ], "summary": "Retrieve a list of logs", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLogsResponse" } } } } } } }, "/logs/{log_id}": { "get": { "operationId": "logs/get", "tags": [ "Logs" ], "summary": "Retrieve a single log", "parameters": [ { "name": "log_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the log." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Log" } } } } } } }, "/automations": { "post": { "operationId": "automations/create", "tags": [ "Automations" ], "summary": "Create an automation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationResponse" } } } } } }, "get": { "operationId": "automations/list", "tags": [ "Automations" ], "summary": "Retrieve a list of automations", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "enabled", "disabled" ] }, "description": "Filter automations by status." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAutomationsResponse" } } } } } } }, "/automations/{automation_id}": { "get": { "operationId": "automations/get", "tags": [ "Automations" ], "summary": "Retrieve a single automation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } } } }, "patch": { "operationId": "automations/update", "tags": [ "Automations" ], "summary": "Update an automation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAutomationRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAutomationResponse" } } } } } }, "delete": { "operationId": "automations/remove", "tags": [ "Automations" ], "summary": "Delete an automation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAutomationResponse" } } } } } } }, "/automations/{automation_id}/duplicate": { "post": { "operationId": "automations/duplicate", "tags": [ "Automations" ], "summary": "Duplicate an automation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAutomationResponse" } } } } } } }, "/automations/{automation_id}/stop": { "post": { "operationId": "automations/stop", "tags": [ "Automations" ], "summary": "Stop an automation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopAutomationResponse" } } } } } } }, "/automations/{automation_id}/runs": { "get": { "operationId": "automations/list-runs", "tags": [ "Automations" ], "summary": "Retrieve a list of automation runs", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter runs by status. Comma-separated list of: running, completed, failed, cancelled." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAutomationRunsResponse" } } } } } } }, "/automations/{automation_id}/runs/{run_id}": { "get": { "operationId": "automations/get-run", "tags": [ "Automations" ], "summary": "Retrieve a single automation run", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the automation run." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRun" } } } } } } }, "/events": { "post": { "operationId": "events/create", "tags": [ "Events" ], "summary": "Create an event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" } } } } } }, "get": { "operationId": "events/list", "tags": [ "Events" ], "summary": "Retrieve a list of events", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } } } } }, "/events/send": { "post": { "operationId": "events/send", "tags": [ "Events" ], "summary": "Send an event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEventRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEventResponse" } } } } } } }, "/events/{identifier}": { "get": { "operationId": "events/get", "tags": [ "Events" ], "summary": "Retrieve a single event", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The event ID (UUID) or event name." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } } } }, "patch": { "operationId": "events/update", "tags": [ "Events" ], "summary": "Update an event", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The event ID (UUID) or event name." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventResponse" } } } } } }, "delete": { "operationId": "events/remove", "tags": [ "Events" ], "summary": "Delete an event", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The event ID (UUID) or event name." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveEventResponse" } } } } } } }, "/suppressions": { "post": { "operationId": "suppressions/add", "tags": [ "Suppressions" ], "summary": "Create a suppression", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuppressionOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuppressionResponseSuccess" } } } } } }, "get": { "operationId": "suppressions/list", "tags": [ "Suppressions" ], "summary": "Retrieve a list of suppressions", "parameters": [ { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "bounce", "complaint", "manual" ] }, "description": "Filter suppressions by origin." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSuppressionsResponseSuccess" } } } } } } }, "/suppressions/batch/add": { "post": { "operationId": "suppressions/batch-add", "tags": [ "Suppressions" ], "summary": "Add up to 100 suppressions at once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAddSuppressionsOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAddSuppressionsResponseSuccess" } } } } } } }, "/suppressions/batch/remove": { "post": { "operationId": "suppressions/batch-remove", "tags": [ "Suppressions" ], "summary": "Remove up to 100 suppressions at once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRemoveSuppressionsOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRemoveSuppressionsResponseSuccess" } } } } } } }, "/suppressions/{suppression}": { "get": { "operationId": "suppressions/get", "tags": [ "Suppressions" ], "summary": "Retrieve a single suppression by ID or email", "parameters": [ { "name": "suppression", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Suppression ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSuppressionResponseSuccess" } } } } } }, "delete": { "operationId": "suppressions/remove", "tags": [ "Suppressions" ], "summary": "Remove a single suppression by ID or email", "parameters": [ { "name": "suppression", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Suppression ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSuppressionResponseSuccess" } } } } } } }, "/usage": { "get": { "operationId": "usage/get", "tags": [ "Usage" ], "summary": "Retrieve account usage", "description": "Retrieve your account's current usage and plan limits.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsageResponseSuccess" } } } } } } }, "/inboxes": { "post": { "operationId": "inboxes/create", "tags": [ "Inboxes" ], "summary": "Create an inbox", "description": "Creates an inbox that sends and receives email at an address on one of your domains. The domain must belong to the team. Without `forwarding`, the domain must have receiving enabled, with DKIM and SPF verified and the inbound MX record verified or pending. With `forwarding` set to `true`, the domain only needs DKIM and SPF verified for sending, and Resend generates a `receiving_address` on the team inbound domain, and a team without an inbound domain gets a 422. A domain that does not meet these rules returns a 422 validation_error. An address or receiving address that is already in use returns a 409. A team that has reached the inbox limit of its plan returns a 403 validation_error. A blocked account returns a 451.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxResponseSuccess" } } } } } }, "get": { "operationId": "inboxes/list", "tags": [ "Inboxes" ], "summary": "Retrieve a list of inboxes", "description": "Returns the inboxes of the team, newest first. The list items carry fewer fields than a single inbox. Retrieve an inbox to get all its fields. The `after` and `before` cursors take an inbox ID, and only one of them can be passed, or the request returns a 422. A value that is not a UUID returns a 422, and an unknown ID returns a 404.", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboxesResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}": { "get": { "operationId": "inboxes/get", "tags": [ "Inboxes" ], "summary": "Retrieve a single inbox by ID or email address", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboxResponseSuccess" } } } } } }, "patch": { "operationId": "inboxes/update", "tags": [ "Inboxes" ], "summary": "Update an existing inbox by ID or email address", "description": "Updates the internal name of the inbox or the name recipients see when mail is sent from it. At least one of `name` or `from_name` is required.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxResponseSuccess" } } } } } }, "delete": { "operationId": "inboxes/remove", "tags": [ "Inboxes" ], "summary": "Remove an existing inbox by ID or email address", "description": "Removes the inbox. An inbox that does not exist or was already removed returns a 404 not_found.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveInboxResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/agent": { "get": { "operationId": "inboxes/get-agent", "tags": [ "Inboxes" ], "summary": "Retrieve the agent settings for an inbox", "description": "Returns the agent settings of the inbox. An inbox without a configured agent returns empty settings: `instructions` and `tone` are null and `actions` is an empty array.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboxAgentResponseSuccess" } } } } } }, "patch": { "operationId": "inboxes/update-agent", "tags": [ "Inboxes" ], "summary": "Update the agent settings for an inbox", "description": "Updates the agent settings of the inbox. The agent is created when the inbox has none. Omitted fields keep their current value.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxAgentOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxAgentResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/labels": { "get": { "operationId": "inboxes/list-labels", "tags": [ "Inboxes" ], "summary": "Retrieve a list of inbox labels", "description": "Returns every label on the inbox, oldest first. The list is not paginated.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboxLabelsResponseSuccess" } } } } } }, "post": { "operationId": "inboxes/create-label", "tags": [ "Inboxes" ], "summary": "Create a label on an inbox", "description": "A label is a named, colored tag that belongs to one inbox. An inbox can have at most 100 labels. Label names are unique per inbox, compared without case. A duplicate name or a full inbox returns a 422 validation_error.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxLabelOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxLabelResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/labels/{label_id}": { "patch": { "operationId": "inboxes/update-label", "tags": [ "Inboxes" ], "summary": "Update an existing inbox label", "description": "Renames or recolors a label. Omitted fields keep their current value. A new name must not match another label on the inbox, compared without case, or the request returns a 422 validation_error.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Label ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxLabelOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxLabelResponseSuccess" } } } } } }, "delete": { "operationId": "inboxes/remove-label", "tags": [ "Inboxes" ], "summary": "Remove an existing inbox label", "description": "Deletes the label and removes it from every thread that carries it.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Label ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveInboxLabelResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads": { "get": { "operationId": "inboxes/list-threads", "tags": [ "Inboxes" ], "summary": "Retrieve a list of inbox threads", "description": "Returns the threads in an inbox, most recently active first. A thread is a conversation made up of one or more emails. The `after` and `before` cursors take a thread ID, and only one of them can be passed. A cursor that is not a UUID, such as a date, returns a 422 validation_error. A cursor thread that is not in the selected folders returns a 404. To find threads by text, sender, recipient, attachment, or date, use the search threads endpoint.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "folders", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "inbox", "archive", "spam", "sent", "trash" ] } }, "description": "Comma-separated folders to list, for example `inbox,sent`. Repeating the parameter returns a 422 validation_error. A thread is returned when any of its emails is in one of the folders, so a thread in `inbox` with an email you sent matches both `inbox` and `sent`. Defaults to `inbox`, or to `inbox,archive,sent` when `labels` is set. `spam` and `trash` are only included when you name them.", "example": [ "inbox", "sent" ] }, { "name": "labels", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "uuid" } }, "description": "Comma-separated label IDs. Returns threads with any of these labels. Up to 50 IDs. An ID that does not exist in the inbox returns a 404. Repeating the parameter returns a 422 validation_error.", "example": [ "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" ] }, { "name": "read", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` returns threads where every email is read. `false` returns threads with at least one unread email. Only the literal values `true` and `false` are accepted." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboxThreadsResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/search": { "get": { "operationId": "inboxes/search-threads", "tags": [ "Inboxes" ], "summary": "Search the threads of an inbox", "description": "Finds threads by the text of their emails, who sent or received them, whether they have attachments, and their dates. Results are ordered by latest activity, newest first, and paginate like the list threads endpoint, so a cursor that is not a thread ID returns a 422. Search can be up to about a minute behind new emails. Different parameters combine, so a thread must match all of them. `folders`, `labels`, and `read` apply to the thread. `query`, `from`, `to`, `cc`, `bcc`, `has_attachment`, `start_date`, and `end_date` must all match the same email in the thread. When any of these email filters is set, the matching email must itself be in one of `folders`. For `sent`, that means an email the inbox sent. When more than 10,000 threads match, search covers the 10,000 with the newest matching email.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Free text to search for in the subject, body, sender, recipients, and attachment names. Every word must match. Wrap words in double quotes to match an exact phrase. Start a word or quoted phrase with `-` to exclude it. Max 256 characters and 32 words.", "example": "invoice -draft" }, { "name": "from", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "description": "Comma-separated senders. Each value matches part of the sender's address or name, without case. Returns threads that match any of them. Up to 20 values. Repeating the parameter returns a 422 validation_error.", "example": [ "isabella@example.com", "carolina@example.com" ] }, { "name": "to", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "description": "Comma-separated recipients, matched the same way as `from`. Up to 20 values. Repeating the parameter returns a 422 validation_error." }, { "name": "cc", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "description": "Comma-separated CC recipients, matched the same way as `from`. Up to 20 values. Repeating the parameter returns a 422 validation_error." }, { "name": "bcc", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "description": "Comma-separated BCC recipients, matched the same way as `from`. Up to 20 values. Repeating the parameter returns a 422 validation_error." }, { "name": "has_attachment", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` matches emails with an attachment. `false` matches emails without one. Only the literal values `true` and `false` are accepted." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Matches emails sent on or after this date. Accepts a date like `2026-09-01` or an ISO 8601 timestamp, in UTC unless the timestamp has an offset. An empty value returns a 422.", "example": "2026-09-01" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Matches emails sent on or before this date. Same formats as `start_date`. A date covers that whole day, so `start_date=2026-09-01&end_date=2026-09-30` covers all of September. A timestamp is used as given. An `end_date` before `start_date` returns a 422 validation_error. An empty value returns a 422.", "example": "2026-09-30" }, { "name": "folders", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "inbox", "archive", "spam", "sent", "trash" ] } }, "description": "Comma-separated folders to search, for example `inbox,sent`. Repeating the parameter returns a 422 validation_error. A thread is returned when any of its emails is in one of the folders. Defaults to `inbox`, or to `inbox,archive,sent` when `labels` is set. `spam` and `trash` are only included when you name them.", "example": [ "inbox", "sent" ] }, { "name": "labels", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "uuid" } }, "description": "Comma-separated label IDs. Returns threads with any of these labels. Up to 50 IDs. An ID that does not exist in the inbox returns a 404. Repeating the parameter returns a 422 validation_error.", "example": [ "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" ] }, { "name": "read", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` returns threads where every email is read. `false` returns threads with at least one unread email. Only the literal values `true` and `false` are accepted." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchInboxThreadsResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}": { "get": { "operationId": "inboxes/get-thread", "tags": [ "Inboxes" ], "summary": "Retrieve a single inbox thread", "description": "Returns the thread summary. The emails in the thread are listed with the list thread emails endpoint.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboxThreadResponseSuccess" } } } } } }, "patch": { "operationId": "inboxes/update-thread", "tags": [ "Inboxes" ], "summary": "Update an existing inbox thread", "description": "Marks a thread read or unread, or moves it to a folder. At least one of `read` or `folder` is required. To change the labels of a thread, use the add, set, and remove thread labels endpoints. This endpoint ignores the removed `add_label_ids` and `remove_label_ids` fields, so a body with only those fields returns a 422 validation_error. Moving a thread out of `trash` restores it and clears its deletion deadline. The changes apply in this order: `read`, then `folder`. They are not atomic.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxThreadOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxThreadResponseSuccess" } } } } } }, "delete": { "operationId": "inboxes/remove-thread", "tags": [ "Inboxes" ], "summary": "Remove an existing inbox thread", "description": "Moves the thread to `trash` and schedules it for deletion in 30 days. This is reversible. To restore the thread, update its `folder` to `inbox`, `archive`, or `spam`, which also clears the deletion deadline.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveInboxThreadResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/labels": { "post": { "operationId": "inboxes/add-thread-labels", "tags": [ "Inboxes" ], "summary": "Add labels to an inbox thread", "description": "Applies one or more labels to the thread. Labels already on the thread stay on it. The response lists every label on the thread after the change. A label ID that is not a label of the inbox returns a 404 `Label not found.`, and nothing changes. A thread that does not exist in the inbox returns a 404 `Thread not found.`. To replace the labels of the thread, use the set thread labels endpoint.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddInboxThreadLabelsOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddInboxThreadLabelsResponseSuccess" } } } } } }, "put": { "operationId": "inboxes/set-thread-labels", "tags": [ "Inboxes" ], "summary": "Set the labels of an inbox thread", "description": "Replaces every label on the thread with the given labels, in one atomic change. Labels on the thread that are not in the list are taken off it. The labels themselves are kept. An empty array takes every label off the thread. The response lists every label on the thread after the change. A label ID that is not a label of the inbox returns a 404 `Label not found.`, and nothing changes. A thread that does not exist in the inbox returns a 404 `Thread not found.`.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInboxThreadLabelsOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInboxThreadLabelsResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/labels/{label_id}": { "delete": { "operationId": "inboxes/remove-thread-label", "tags": [ "Inboxes" ], "summary": "Remove a label from an inbox thread", "description": "Takes one label off the thread. The label itself is kept, and stays on every other thread that carries it. To delete the label, use the remove inbox label endpoint. The response lists every label on the thread after the change. A label that is not on the thread returns a 200 with the current labels. A label ID that is not a label of the inbox returns a 404 `Label not found.`. A thread that does not exist in the inbox returns a 404 `Thread not found.`.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." }, { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Label ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveInboxThreadLabelResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/emails": { "get": { "operationId": "inboxes/list-thread-emails", "tags": [ "Inboxes" ], "summary": "Retrieve a list of thread emails", "description": "Returns the messages of a thread, oldest first. Pass the `id` of the last message as `after` to get the next, newer page. Pass the `id` of the first message as `before` to get the previous, older page. Passing both `after` and `before`, or a cursor that is not a UUID, returns a 422. A cursor that is not a message of the thread returns a 404.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboxThreadEmailsResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}": { "get": { "operationId": "inboxes/get-thread-email", "tags": [ "Inboxes" ], "summary": "Retrieve a single thread email", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." }, { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Email ID, as returned in `data[].id` by the list thread emails endpoint." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboxThreadEmailResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/reply": { "post": { "operationId": "inboxes/reply-thread-email", "tags": [ "Inboxes" ], "summary": "Reply to a thread email", "description": "Sends a reply from the inbox address right away, with no stored draft. The `to` recipients come from the message you reply to. For a message the inbox received, the reply goes to its `Reply-To` addresses, or to its sender when it has no `Reply-To`. For a message the inbox sent, the reply goes to that message's `to` recipients. Set `reply_all` to also copy the other recipients of the message. The reply threads under the message through the `In-Reply-To` and `References` headers. When no recipient can be found for the reply, the request returns a 422. The whole email, encoded, can be at most 40 MB, or the request returns a 422.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "A unique key for the request, so the reply is sent only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the `idempotent-replayed: true` header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 `invalid_idempotency_key`. [Learn more](https://resend.com/docs/dashboard/emails/idempotency-keys)" }, { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." }, { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Email ID of the message to reply to, as returned in `data[].id` by the list thread emails endpoint." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyInboxThreadEmailOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyInboxThreadEmailResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/forward": { "post": { "operationId": "inboxes/forward-thread-email", "tags": [ "Inboxes" ], "summary": "Forward a thread email", "description": "Forwards a message from the inbox address right away, with no stored draft. The original message is quoted under a forwarded-message banner, below the optional `html` or `text` note. The attachments of the original message are sent with the forward, together with any `attachments` you add. The request returns a 422 when they exceed 25 MB of `content` in total. An original attachment that was sent from a URL (`path`) cannot be forwarded, and the request returns a 422. The whole email, encoded, can be at most 40 MB, or the request returns a 422.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "A unique key for the request, so the forward is sent only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the `idempotent-replayed: true` header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 `invalid_idempotency_key`. [Learn more](https://resend.com/docs/dashboard/emails/idempotency-keys)" }, { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Thread ID." }, { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Email ID of the message to forward, as returned in `data[].id` by the list thread emails endpoint." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardInboxThreadEmailOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardInboxThreadEmailResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/drafts": { "get": { "operationId": "inboxes/list-drafts", "tags": [ "Inboxes" ], "summary": "Retrieve a list of drafts", "description": "Returns the unsent drafts on the inbox, most recently updated first. The `after` and `before` cursors take a Draft ID from the current page, and only one of them can be passed. A cursor that is not a UUID, or both cursors together, return a 422. A cursor that is not an unsent draft on this inbox returns a 404.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboxDraftsResponseSuccess" } } } } } }, "post": { "operationId": "inboxes/create-draft", "tags": [ "Inboxes" ], "summary": "Create a draft", "description": "Creates an unsent draft on the inbox. Omit `thread_id` and `reply_to_email_id` for a draft that starts a new thread. Pass both together for a reply draft in an existing thread. A reply draft without `to` is addressed to the sender of the email it replies to, or to its Reply-To when set. For an email the inbox sent, it defaults to that email's `to` recipients. Send `to: []` to leave it empty. At least one of `to`, `cc`, `bcc`, `subject`, `text`, `html` or `attachments` must be non-empty. The combined recipients of `to`, `cc` and `bcc` cannot exceed 50. Attachments are stored on the draft, so each one needs `content`, `filename` and `content_type`. Returns 201 for a new draft. Only one unsent reply draft can target an email, so a reply draft request for an email that already has one returns 200 with the ID of the existing draft. An unknown `thread_id`, or a `reply_to_email_id` that is not in that thread, returns a 404. That request ignores every other field, except `attachments`, which replaces the attachments of the existing draft when sent. A reply draft created without `subject` stores an empty subject. When it is sent, it takes the thread subject, prefixed with `Re:` when it does not already start with it.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "A unique key for the request, so the draft is created only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the `idempotent-replayed: true` header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 `invalid_idempotency_key`. [Learn more](https://resend.com/docs/dashboard/emails/idempotency-keys)" }, { "$ref": "#/components/parameters/InboxIdOrEmailAddress" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxDraftOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxDraftResponseSuccess" } } } }, "200": { "description": "The reply draft for this email already exists. The response holds the ID of the existing draft, and the request fields other than `attachments` are not applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxDraftResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/drafts/{draft_id}": { "get": { "operationId": "inboxes/get-draft", "tags": [ "Inboxes" ], "summary": "Retrieve a single draft", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Draft ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboxDraftResponseSuccess" } } } } } }, "patch": { "operationId": "inboxes/update-draft", "tags": [ "Inboxes" ], "summary": "Update an existing draft", "description": "Updates the content of an unsent draft. Omitted fields are left unchanged. Send at least one of `to`, `cc`, `bcc`, `subject`, `text`, `html` or `attachments`. Sending `attachments` replaces every attachment on the draft. A request that sets `text` or `html` replaces the whole body. The body part you omit from that request becomes `null`. The merged draft must still contain at least one non-empty field, and its combined recipients cannot exceed 50. A draft that was already sent, or that changed during the request, returns a 409. The response holds only the Draft ID. Retrieve the draft to read its content.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Draft ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxDraftOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxDraftResponseSuccess" } } } } } }, "delete": { "operationId": "inboxes/remove-draft", "tags": [ "Inboxes" ], "summary": "Remove an existing draft", "description": "Discards an unsent draft. A draft that was already sent, or that changed during the request, returns a 409.", "parameters": [ { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Draft ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveInboxDraftResponseSuccess" } } } } } } }, "/inboxes/{inbox_id}/drafts/{draft_id}/send": { "post": { "operationId": "inboxes/send-draft", "tags": [ "Inboxes" ], "summary": "Send a draft", "description": "Sends the draft from the inbox address. A reply draft is sent in its thread. A draft without a thread starts a new thread. The draft must have at least one `to` recipient and `html` or `text`, or the request returns a 422. A standalone draft also needs a non-empty `subject`. A reply draft with an empty `subject` is sent with the thread subject, prefixed with `Re:` when it does not already start with it. A draft that was already sent returns a 409. The request body is optional and takes only `headers`. The whole email, encoded, can be at most 40 MB, or the request returns a 422.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "A unique key for the request, so the draft is sent only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the `idempotent-replayed: true` header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 `invalid_idempotency_key`. [Learn more](https://resend.com/docs/dashboard/emails/idempotency-keys)" }, { "$ref": "#/components/parameters/InboxIdOrEmailAddress" }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Draft ID." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInboxDraftOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInboxDraftResponseSuccess" } } } } } } } }, "webhooks": { "email.sent": { "post": { "summary": "Email sent", "description": "Occurs whenever the API request was successful. Resend will attempt to deliver the message to the recipient's mail server.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSentEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.delivered": { "post": { "summary": "Email delivered", "description": "Occurs whenever Resend successfully delivered the email to the recipient's mail server.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDeliveredEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.delivery_delayed": { "post": { "summary": "Email delivery delayed", "description": "Occurs whenever the email couldn't be delivered due to a temporary issue, such as the recipient's inbox being full or the receiving server experiencing a transient issue.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDeliveryDelayedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.bounced": { "post": { "summary": "Email bounced", "description": "Occurs whenever the recipient's mail server permanently rejected the email.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBouncedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.complained": { "post": { "summary": "Email complained", "description": "Occurs whenever the email was successfully delivered, but the recipient marked it as spam.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailComplainedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.opened": { "post": { "summary": "Email opened", "description": "Occurs whenever the recipient opened the email. Requires open tracking to be enabled.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOpenedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.clicked": { "post": { "summary": "Email clicked", "description": "Occurs whenever the recipient clicks on an email link. Requires click tracking to be enabled.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailClickedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.failed": { "post": { "summary": "Email failed", "description": "Occurs whenever the email failed to send due to an error such as invalid recipients, API key problems, domain verification issues, email quota limits, or other sending failures.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.scheduled": { "post": { "summary": "Email scheduled", "description": "Occurs whenever the email is scheduled to be sent.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailScheduledEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.suppressed": { "post": { "summary": "Email suppressed", "description": "Occurs whenever the email is suppressed by Resend, such as when the recipient's address is on the account-level suppression list.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSuppressedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "email.received": { "post": { "summary": "Email received", "description": "Occurs whenever Resend successfully receives an inbound email on a receiving domain.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailReceivedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "contact.created": { "post": { "summary": "Contact created", "description": "Occurs whenever a contact was successfully created. Note: when importing multiple contacts via CSV, this event is not triggered.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "contact.updated": { "post": { "summary": "Contact updated", "description": "Occurs whenever a contact was successfully updated.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "contact.deleted": { "post": { "summary": "Contact deleted", "description": "Occurs whenever a contact was successfully deleted.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDeletedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "contact.topics.updated": { "post": { "summary": "Contact topics updated", "description": "Occurs whenever a contact's topic subscriptions were updated.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTopicsUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "domain.created": { "post": { "summary": "Domain created", "description": "Occurs when a domain was successfully created.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "domain.updated": { "post": { "summary": "Domain updated", "description": "Occurs when a domain was successfully updated.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "domain.deleted": { "post": { "summary": "Domain deleted", "description": "Occurs when a domain was successfully deleted.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDeletedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "suppression.added": { "post": { "summary": "Suppression added", "description": "Occurs whenever an email address was added to the suppression list.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionAddedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "suppression.removed": { "post": { "summary": "Suppression removed", "description": "Occurs whenever an email address was removed from the suppression list.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionRemovedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "topic.created": { "post": { "summary": "Topic created", "description": "Occurs whenever a topic was successfully created.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "topic.updated": { "post": { "summary": "Topic updated", "description": "Occurs whenever a topic was successfully updated.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "topic.deleted": { "post": { "summary": "Topic deleted", "description": "Occurs whenever a topic was successfully deleted.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicDeletedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.created": { "post": { "summary": "Inbox created", "description": "Occurs whenever an inbox was created.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.updated": { "post": { "summary": "Inbox updated", "description": "Occurs whenever the settings of an inbox changed.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.deleted": { "post": { "summary": "Inbox deleted", "description": "Occurs whenever an inbox was deleted. The payload carries only the inbox ID.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDeletedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.thread.created": { "post": { "summary": "Inbox thread created", "description": "Occurs whenever the first email of a thread landed in an inbox, inbound or outbound. The `source` is always `system`, because the email pipeline sends this event, even when the API or an agent sent the email.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.email.received": { "post": { "summary": "Inbox email received", "description": "Occurs whenever an inbound email was added to a thread. The `source` is always `system`.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmailReceivedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.email.sent": { "post": { "summary": "Inbox email sent", "description": "Occurs whenever an outbound email was accepted for delivery and added to a thread. The `source` is always `system`. When the email comes from a draft, `inbox.draft.sent` is also sent, from the send call. The two events come from separate paths, so their delivery order is not fixed.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmailSentEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.thread.folder.updated": { "post": { "summary": "Inbox thread folder updated", "description": "Occurs whenever a thread moved between folders. Moving a thread to a label can send both this event and `inbox.thread.labels.updated` for the same thread.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadFolderUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.thread.assigned": { "post": { "summary": "Inbox thread assigned", "description": "Occurs whenever a thread was assigned or reassigned.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadAssignedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.thread.unassigned": { "post": { "summary": "Inbox thread unassigned", "description": "Occurs whenever a thread was unassigned.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadUnassignedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.thread.labels.updated": { "post": { "summary": "Inbox thread labels updated", "description": "Occurs whenever labels were applied to or removed from a thread. One event lists every label that one request added to or removed from the thread. A request that changes no label sends no event. Deleting a label does not send this event for the threads that had it.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadLabelsUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.draft.created": { "post": { "summary": "Inbox draft created", "description": "Occurs whenever a draft was created, standalone or reply.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDraftCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.draft.updated": { "post": { "summary": "Inbox draft updated", "description": "Occurs whenever a draft was edited.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDraftUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.draft.sent": { "post": { "summary": "Inbox draft sent", "description": "Occurs whenever a draft was sent. This event fires from the send call. `inbox.email.sent` follows once the email is accepted for delivery.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDraftSentEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } }, "inbox.draft.deleted": { "post": { "summary": "Inbox draft deleted", "description": "Occurs whenever a draft was discarded. The draft is already gone, so the payload has no `draft` object.", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDraftDeletedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status code to acknowledge receipt of the event." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "parameters": { "PaginationLimit": { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return." }, "PaginationAfter": { "in": "query", "name": "after", "required": false, "schema": { "type": "string" }, "description": "Return items after this cursor." }, "PaginationBefore": { "in": "query", "name": "before", "required": false, "schema": { "type": "string" }, "description": "Return items before this cursor." }, "InboxIdOrEmailAddress": { "in": "path", "name": "inbox_id", "required": true, "schema": { "type": "string" }, "description": "The Inbox ID or the inbox email address, such as `support@acme.com`. A value that contains `@` must be a valid email address, and any other value must be a UUID, or the request returns a 422. The address match is case-insensitive and never falls back to the inbox `name`. An address that matches no inbox returns a 404.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" } }, "schemas": { "SendEmailRequest": { "type": "object", "required": [ "from", "to", "subject" ], "properties": { "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, "to": { "description": "Recipient email address. For multiple addresses, send as an array of strings. Max 50.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 } ] }, "subject": { "type": "string", "description": "Email subject." }, "bcc": { "description": "Bcc recipient email address. For multiple addresses, send as an array of strings.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "cc": { "description": "Cc recipient email address. For multiple addresses, send as an array of strings.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "reply_to": { "description": "Reply-to email address. For multiple addresses, send as an array of strings.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "html": { "type": "string", "description": "The HTML version of the message." }, "text": { "type": "string", "description": "The plain text version of the message." }, "template": { "allOf": [ { "$ref": "#/components/schemas/EmailTemplateInput" }, { "description": "Use a published template to send the email. If provided, do not include html or text." } ] }, "headers": { "type": "object", "description": "Custom headers to add to the email." }, "scheduled_at": { "type": "string", "description": "Schedule email to be sent later. The date should be in ISO 8601 format." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "topic_id": { "type": "string", "description": "The topic ID to scope the email to. If the recipient is a contact and opted-in to the topic, the email is sent. If opted-out, the email is not sent. If the recipient is not a contact, the email is sent if the topic's default subscription is opt_in." } } }, "Attachment": { "type": "object", "properties": { "content": { "type": "string", "format": "binary", "description": "Content of an attached file." }, "filename": { "type": "string", "description": "Name of attached file." }, "path": { "type": "string", "description": "Path where the attachment file is hosted" }, "content_type": { "type": "string", "description": "Optional content type for the attachment, if not set it will be derived from the filename property" }, "content_id": { "type": "string", "description": "Content ID for embedding inline images using cid references (e.g., cid:image001)." } } }, "Tag": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the email tag. It can only contain ASCII letters (a–z, A–Z), numbers (0–9), underscores (_), or dashes (-). It can contain no more than 256 characters." }, "value": { "type": "string", "description": "The value of the email tag.It can only contain ASCII letters (a–z, A–Z), numbers (0–9), underscores (_), or dashes (-). It can contain no more than 256 characters." } } }, "EmailTemplateInput": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the published email template." }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Template variables object with key/value pairs.", "example": { "variableName": "Sign up now", "variableName2": 123 } } }, "required": [ "id" ] }, "SendEmailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the sent email." } } }, "UpdateEmailOptions": { "type": "object", "properties": { "scheduled_at": { "type": "string", "description": "Schedule email to be sent later. The date should be in ISO 8601 format." } } }, "ShareEmailOptions": { "type": "object", "properties": { "expires_in": { "type": "string", "description": "How long the link stays valid for, as a duration like `10m`, `2 hours`, or `1 day`. Defaults to `48h` and cannot exceed 48 hours." } } }, "ShareEmailResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "email" }, "id": { "type": "string", "description": "The ID of the email.", "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }, "url": { "type": "string", "description": "The shareable link, valid until it expires.", "example": "https://resend.com/shared?token=eyJhbGciOiJIUzI1NiJ9..." } } }, "Email": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "email" }, "id": { "type": "string", "description": "The ID of the email.", "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }, "message_id": { "type": "string", "description": "The Message-ID header value of the email.", "example": "<202301010000.4ef9a417@email.example.com>" }, "to": { "type": "array", "items": { "type": "string", "description": "The email addresses of the recipients." }, "example": [ "delivered@resend.dev" ] }, "from": { "type": "string", "description": "The email address of the sender.", "example": "Acme " }, "created_at": { "type": "string", "description": "The date and time the email was created.", "example": "2023-04-03 22:13:42.674981+00" }, "subject": { "type": "string", "description": "The subject line of the email.", "example": "Hello World" }, "html": { "type": "string", "description": "The HTML body of the email.", "example": "Congrats on sending your first email!" }, "text": { "type": "string", "description": "The plain text body of the email." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "The email addresses of the blind carbon copy recipients." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "The email addresses of the carbon copy recipients." }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "The email addresses to which replies should be sent." }, "last_event": { "type": "string", "description": "The status of the email.", "enum": [ "bounced", "canceled", "clicked", "complained", "delivered", "delivery_delayed", "failed", "opened", "queued", "scheduled", "sent", "suppressed" ], "example": "delivered" } } }, "ListEmailsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing email information.", "items": { "$ref": "#/components/schemas/Email" } } } }, "GetEmailsMetricsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "metrics" }, "start_date": { "type": "string", "description": "The start of the requested date range, as an ISO 8601 datetime.", "example": "2026-07-01T00:00:00.000Z" }, "end_date": { "type": "string", "description": "The end of the requested date range, as an ISO 8601 datetime.", "example": "2026-07-08T00:00:00.000Z" }, "metrics": { "type": "array", "description": "The metrics included in the response.", "items": { "type": "string" } }, "dimensions": { "type": "array", "description": "The dimensions the response is broken down by.", "items": { "type": "string", "enum": [ "period", "domain", "email", "broadcast" ] } }, "granularity": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly" ], "description": "The bucket size used when `period` is in `dimensions`." }, "totals": { "type": "object", "description": "The requested metrics, totaled over the whole date range.", "additionalProperties": { "type": "number" } }, "data": { "type": "array", "description": "One row per unique combination of the requested `dimensions`. Omitted when `dimensions` is empty.", "items": { "$ref": "#/components/schemas/EmailMetricsDataRow" } } } }, "EmailMetricsDataRow": { "type": "object", "description": "A single breakdown row. Which dimension fields are present depends on the requested `dimensions`; which metric fields are present depends on the requested `metrics`.", "properties": { "period": { "type": "string", "description": "Present when `period` is in `dimensions`." }, "domain_id": { "type": "string", "format": "uuid", "description": "Present when `domain` is in `dimensions`." }, "domain_name": { "type": "string", "description": "Present when `domain` is in `dimensions`." }, "email_id": { "type": "string", "format": "uuid", "description": "Present when `email` is in `dimensions`." }, "broadcast_id": { "type": "string", "format": "uuid", "description": "Present when `broadcast` is in `dimensions`." }, "broadcast_name": { "type": "string", "description": "Present when `broadcast` is in `dimensions`." } }, "additionalProperties": { "type": "number" } }, "GetUsageResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "usage" }, "emails": { "type": "object", "properties": { "daily": { "type": "object", "properties": { "used": { "type": "integer", "description": "Emails sent and received in the current day." }, "limit": { "type": [ "integer", "null" ], "description": "The daily plan limit, or `null` when the account has a monthly sending subscription." }, "sent": { "type": "integer", "description": "Emails sent today." }, "received": { "type": "integer", "description": "Emails received today." }, "resets_at": { "type": "string", "description": "When the daily counter resets, as an ISO 8601 datetime." } } }, "monthly": { "type": "object", "properties": { "used": { "type": "integer", "description": "Emails sent and received in the current billing period." }, "limit": { "type": "integer", "description": "The monthly plan limit." }, "sent": { "type": "integer", "description": "Emails sent this billing period." }, "received": { "type": "integer", "description": "Emails received this billing period." }, "resets_at": { "type": "string", "description": "When the monthly counter resets, as an ISO 8601 datetime." } } } } }, "contacts": { "type": "object", "properties": { "used": { "type": "integer", "description": "Contacts currently stored." }, "limit": { "type": "integer", "description": "The plan limit." } } }, "segments": { "type": "object", "properties": { "used": { "type": "integer", "description": "Segments currently created." }, "limit": { "type": [ "integer", "null" ], "description": "The plan limit, or `null` when the account has a contacts subscription." } } }, "broadcasts": { "type": "object", "properties": { "used": { "type": "integer", "description": "Broadcasts sent." }, "limit": { "type": "null", "description": "Always `null`; broadcasts aren't limited." } } }, "ai_credits": { "type": "object", "properties": { "used": { "type": "integer", "description": "AI credits consumed in the current period." }, "limit": { "type": [ "integer", "null" ], "description": "The plan limit, or `null` when unlimited." }, "next_increase_at": { "type": [ "string", "null" ], "description": "When the AI credit balance next increases, as an ISO 8601 datetime, or `null` when unknown." } } }, "automation_runs": { "type": "object", "properties": { "used": { "type": "integer", "description": "Automation runs in the current billing period." }, "limit": { "type": "integer", "description": "The plan limit." }, "resets_at": { "type": "string", "description": "When the counter resets, as an ISO 8601 datetime." } } }, "domains": { "type": "object", "properties": { "used": { "type": "integer", "description": "Domains currently added." }, "limit": { "type": [ "integer", "null" ], "description": "The plan limit, or `null` when unlimited." } } }, "rate_limit": { "type": "object", "properties": { "limit": { "type": "integer", "description": "The number of requests allowed per `duration`." }, "duration": { "type": "string", "description": "The rate-limit window, e.g. `'1000ms'`." } } } } }, "CreateBatchEmailsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the sent email." } } } } } }, "DomainCapabilities": { "type": "object", "description": "Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.", "properties": { "sending": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Enable or disable sending emails from this domain." }, "receiving": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Enable or disable receiving emails to this domain." } } }, "CreateDomainRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the domain you want to create." }, "region": { "type": "string", "enum": [ "us-east-1", "eu-west-1", "sa-east-1", "ap-northeast-1" ], "default": "us-east-1", "description": "The region where emails will be sent from. Possible values are us-east-1 | eu-west-1 | sa-east-1 | ap-northeast-1" }, "custom_return_path": { "type": "string", "description": "For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld)." }, "open_tracking": { "type": "boolean", "description": "Track the open rate of each email." }, "click_tracking": { "type": "boolean", "description": "Track clicks within the body of each HTML email." }, "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ], "default": "opportunistic", "description": "TLS mode. Opportunistic attempts secure connection but falls back to unencrypted. Enforced requires TLS or email won't be sent." }, "capabilities": { "$ref": "#/components/schemas/DomainCapabilities" }, "tracking_subdomain": { "type": "string", "description": "The subdomain to use for click and open tracking." } } }, "CreateDomainResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the domain." }, "name": { "type": "string", "description": "The name of the domain." }, "created_at": { "type": "string", "description": "The date and time the domain was created.", "example": "2023-10-06 23:47:56.678+00" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "not_started", "partially_verified", "partially_failed" ], "description": "The status of the domain." }, "capabilities": { "$ref": "#/components/schemas/DomainCapabilities" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRecord" } }, "region": { "type": "string", "description": "The region where the domain is hosted." }, "open_tracking": { "type": "boolean", "description": "Whether open tracking is enabled for this domain." }, "click_tracking": { "type": "boolean", "description": "Whether click tracking is enabled for this domain." }, "tracking_subdomain": { "type": "string", "description": "The subdomain used for click and open tracking." } } }, "UpdateDomainOptions": { "type": "object", "properties": { "open_tracking": { "type": "boolean", "description": "Track the open rate of each email." }, "click_tracking": { "type": "boolean", "description": "Track clicks within the body of each HTML email." }, "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ], "description": "enforced | opportunistic.", "default": "opportunistic" }, "capabilities": { "$ref": "#/components/schemas/DomainCapabilities" }, "tracking_subdomain": { "type": "string", "description": "The subdomain to use for click and open tracking." } } }, "DomainRecord": { "type": "object", "properties": { "record": { "type": "string", "enum": [ "SPF", "DKIM", "Receiving", "Tracking", "TrackingCAA" ], "description": "The type of record (SPF for sending, DKIM for sending, Receiving for inbound emails, Tracking & TrackingCAA for click and open tracking)." }, "name": { "type": "string", "description": "The name of the DNS record." }, "type": { "type": "string", "enum": [ "MX", "TXT", "CNAME", "CAA" ], "description": "The DNS record type." }, "ttl": { "type": "string", "description": "The time to live for the record." }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "temporary_failure", "not_started" ], "description": "The status of the record." }, "value": { "type": "string", "description": "The value of the record." }, "priority": { "type": "integer", "description": "The priority of the record (only applicable for MX records)." } } }, "Domain": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "domain" }, "id": { "type": "string", "description": "The ID of the domain.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, "name": { "type": "string", "description": "The name of the domain.", "example": "example.com" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "not_started", "partially_verified", "partially_failed" ], "description": "The status of the domain.", "example": "not_started" }, "created_at": { "type": "string", "description": "The date and time the domain was created.", "example": "2023-04-26 20:21:26.347412+00" }, "region": { "type": "string", "description": "The region where the domain is hosted.", "example": "us-east-1" }, "open_tracking": { "type": "boolean", "description": "Whether open tracking is enabled for this domain." }, "click_tracking": { "type": "boolean", "description": "Whether click tracking is enabled for this domain." }, "tracking_subdomain": { "type": "string", "description": "The subdomain used for click and open tracking." }, "capabilities": { "$ref": "#/components/schemas/DomainCapabilities" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRecord" } } } }, "CreateDomainClaimRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the domain you want to claim." }, "region": { "type": "string", "enum": [ "us-east-1", "eu-west-1", "sa-east-1", "ap-northeast-1" ], "default": "us-east-1", "description": "The region where emails will be sent from. Possible values are us-east-1 | eu-west-1 | sa-east-1 | ap-northeast-1" }, "custom_return_path": { "type": "string", "default": "send", "description": "For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld)." }, "open_tracking": { "type": "boolean", "description": "Track the open rate of each email." }, "click_tracking": { "type": "boolean", "description": "Track clicks within the body of each HTML email." }, "tracking_subdomain": { "type": "string", "description": "The subdomain to use for click and open tracking." } } }, "DomainClaimRecord": { "type": "object", "description": "The TXT record to add to your DNS to prove ownership of the claimed domain.", "properties": { "type": { "type": "string", "enum": [ "TXT" ], "description": "The DNS record type. Always TXT for domain claims.", "example": "TXT" }, "name": { "type": "string", "description": "The name of the DNS record (the domain being claimed).", "example": "example.com" }, "value": { "type": "string", "description": "The value of the TXT record.", "example": "resend-domain-verification=abc123" }, "ttl": { "type": "string", "description": "The time to live for the record.", "example": "Auto" } } }, "DomainClaim": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "domain_claim" }, "id": { "type": "string", "description": "The ID of the claim.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, "name": { "type": "string", "description": "The name of the domain being claimed.", "example": "example.com" }, "status": { "type": "string", "enum": [ "pending", "verified", "completed", "blocked", "expired", "superseded", "canceled", "failed" ], "description": "The status of the claim.", "example": "pending" }, "domain_id": { "type": [ "string", "null" ], "description": "The ID of the placeholder domain created for the claim.", "example": "a1b2c3d4-1176-453e-8fc1-35364d380206" }, "region": { "type": [ "string", "null" ], "enum": [ "us-east-1", "eu-west-1", "sa-east-1", "ap-northeast-1", null ], "description": "The region where the claimed domain will send from.", "example": "us-east-1" }, "record": { "$ref": "#/components/schemas/DomainClaimRecord" }, "blocked_reason": { "type": [ "string", "null" ], "enum": [ "grace_period", "recent_owner_activity", "pending_scheduled_emails", null ], "description": "Why the claim is currently blocked, if applicable.", "example": null }, "failure_reason": { "type": [ "string", "null" ], "description": "Why the claim failed, if applicable.", "example": null }, "created_at": { "type": "string", "description": "The date and time the claim was created.", "example": "2023-04-26 20:21:26.347412+00" }, "expires_at": { "type": "string", "description": "The date and time the claim expires if not verified.", "example": "2023-05-03 20:21:26.347412+00" } } }, "VerifyDomainResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "domain" }, "id": { "type": "string", "description": "The ID of the domain.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" } } }, "ListDomainsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListDomainsItem" } } } }, "ListDomainsItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the domain.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, "name": { "type": "string", "description": "The name of the domain.", "example": "example.com" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "not_started", "partially_verified", "partially_failed" ], "description": "The status of the domain.", "example": "not_started" }, "created_at": { "type": "string", "description": "The date and time the domain was created.", "example": "2023-04-26 20:21:26.347412+00" }, "region": { "type": "string", "description": "The region where the domain is hosted.", "example": "us-east-1" }, "open_tracking": { "type": "boolean", "description": "Whether open tracking is enabled for this domain." }, "click_tracking": { "type": "boolean", "description": "Whether click tracking is enabled for this domain." }, "capabilities": { "$ref": "#/components/schemas/DomainCapabilities" } } }, "UpdateDomainResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the updated domain.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, "object": { "type": "string", "description": "The object type representing the updated domain.", "example": "domain" } } }, "DeleteDomainResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "domain" }, "id": { "type": "string", "description": "The ID of the domain.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, "deleted": { "type": "boolean", "description": "Indicates whether the domain was deleted successfully.", "example": true } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The API key name." }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ], "description": "The API key can have full access to Resend’s API or be only restricted to send emails. * full_access - Can create, delete, get, and update any resource. * sending_access - Can only send emails." }, "domain_id": { "type": "string", "description": "Restrict an API key to send emails only from a specific domain. Only used when the permission is sending_access." } } }, "CreateApiKeyResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the API key." }, "token": { "type": "string", "description": "The token of the API key." } } }, "ListApiKeysResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the API key." }, "name": { "type": "string", "description": "The name of the API key." }, "created_at": { "type": "string", "description": "The date and time the API key was created.", "example": "2023-10-06 23:47:56.678+00" }, "last_used_at": { "type": [ "string", "null" ], "description": "The date and time the API key was last used.", "example": "2023-10-06 23:47:56.678+00" } } }, "ListOAuthGrantsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthGrant" } } } }, "OAuthGrant": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the OAuth grant." }, "client_id": { "type": "string", "description": "The ID of the OAuth client the grant was issued to." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes granted to the OAuth client." }, "created_at": { "type": "string", "description": "The date and time the OAuth grant was created.", "example": "2023-10-06 23:47:56.678+00" }, "revoked_at": { "type": [ "string", "null" ], "description": "The date and time the OAuth grant was revoked, or null if it is still active.", "example": "2023-10-06 23:47:56.678+00" }, "revoked_reason": { "type": [ "string", "null" ], "description": "The reason the OAuth grant was revoked, or null if it is still active." }, "client": { "type": "object", "description": "The OAuth client the grant was issued to.", "properties": { "name": { "type": "string", "description": "The name of the OAuth client." }, "logo_uri": { "type": [ "string", "null" ], "description": "The URL of the OAuth client's logo." } } } } }, "RevokeOAuthGrantResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "oauth_grant" }, "id": { "type": "string", "description": "The ID of the OAuth grant." }, "revoked_at": { "type": "string", "format": "date-time", "description": "The date and time the OAuth grant was revoked.", "example": "2023-10-06T23:47:56.678Z" }, "revoked_reason": { "type": "string", "description": "The reason the OAuth grant was revoked." } } }, "DeleteApiKeyResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "api_key" }, "id": { "type": "string", "description": "The ID of the API key." }, "deleted": { "type": "boolean", "description": "Indicates whether the API key was successfully deleted.", "example": true } } }, "UpdateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The API key name." } } }, "UpdateApiKeyResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "api_key" }, "id": { "type": "string", "description": "The ID of the API key." } } }, "CreateAudienceOptions": { "type": "object", "deprecated": true, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the audience you want to create." } } }, "CreateAudienceResponseSuccess": { "type": "object", "deprecated": true, "properties": { "id": { "type": "string", "description": "The ID of the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object of the audience.", "example": "audience" }, "name": { "type": "string", "description": "The name of the audience.", "example": "Registered Users" } } }, "GetAudienceResponseSuccess": { "type": "object", "deprecated": true, "properties": { "id": { "type": "string", "description": "The ID of the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object of the audience.", "example": "audience" }, "name": { "type": "string", "description": "The name of the audience.", "example": "Registered Users" }, "created_at": { "type": "string", "description": "The date that the object was created.", "example": "2023-10-06 22:59:55.977+00" } } }, "RemoveAudienceResponseSuccess": { "type": "object", "deprecated": true, "properties": { "id": { "type": "string", "description": "The ID of the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object of the audience.", "example": "audience" }, "deleted": { "type": "boolean", "description": "The deleted attribute indicates that the corresponding audience has been deleted.", "example": true } } }, "ListAudiencesResponseSuccess": { "type": "object", "deprecated": true, "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "Array containing audience information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "name": { "type": "string", "description": "Name of the audience.", "example": "Registered Users" }, "created_at": { "type": "string", "description": "Timestamp indicating when the audience was created.", "example": "2023-10-06 22:59:55.977+00" } } } } } }, "CreateContactOptions": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": "string", "description": "First name of the contact.", "example": "Steve" }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Wozniak" }, "unsubscribed": { "type": "boolean", "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", "example": false }, "properties": { "type": "object", "additionalProperties": { "type": [ "string", "number", "null" ] }, "description": "A map of custom property keys and values to create." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The segment ID" } } }, "description": "Array of segment IDs to add the contact to." }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The topic ID." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status for this topic." } } }, "description": "Array of topic subscriptions for the contact." }, "audience_id": { "type": "string", "description": "Unique identifier of the audience to which the contact belongs.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "deprecated": true } } }, "CreateContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the created contact.", "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, "GetContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the contact.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": [ "string", "null" ], "description": "First name of the contact.", "example": "Steve" }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the contact.", "example": "Wozniak" }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact was created.", "example": "2023-10-06 23:47:56.678+00" }, "unsubscribed": { "type": "boolean", "description": "Indicates if the contact is unsubscribed.", "example": false }, "properties": { "type": "object", "additionalProperties": true, "description": "A map of custom property keys and values." } } }, "UpdateContactOptions": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": "string", "description": "First name of the contact.", "example": "Steve" }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Wozniak" }, "unsubscribed": { "type": "boolean", "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", "example": false }, "properties": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "A map of custom property keys and values to update." } } }, "UpdateContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the updated contact.", "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, "RemoveContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the removed contact.", "example": "520784e2-887d-4c25-b53c-4ad46ad38100" }, "deleted": { "type": "boolean", "description": "Indicates whether the contact was successfully deleted.", "example": true } } }, "ListContactsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing contact information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the contact.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": [ "string", "null" ], "description": "First name of the contact.", "example": "Steve" }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the contact.", "example": "Wozniak" }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact was created.", "example": "2023-10-06 23:47:56.678+00" }, "unsubscribed": { "type": "boolean", "description": "Indicates if the contact is unsubscribed.", "example": false } } } } } }, "CreateContactImportOptions": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file to import. Maximum size is 50MB." }, "column_map": { "type": "string", "description": "JSON-encoded object mapping contact fields and custom property keys to CSV column names. Supports `email`, `first_name`, `last_name`, `unsubscribed`, and `properties`. Custom property mappings can include `type` as `string`, `number`, or `boolean`; defaults to `string`.", "example": "{\"email\":\"Email\",\"first_name\":\"First Name\",\"last_name\":\"Last Name\",\"unsubscribed\":\"Unsubscribed\",\"properties\":{\"plan\":{\"column\":\"Plan\",\"type\":\"string\"}}}" }, "on_conflict": { "type": "string", "enum": [ "upsert", "skip" ], "default": "skip", "description": "Strategy to use when an imported contact already exists.", "example": "skip" }, "segments": { "type": "string", "description": "JSON-encoded array of segments to add imported contacts to.", "example": "[{\"id\":\"78261eea-8f8b-4381-83c6-79fa7120f1cf\"}]" }, "topics": { "type": "string", "description": "JSON-encoded array of topic subscriptions to apply to imported contacts. Each `subscription` must be `opt_in` or `opt_out`.", "example": "[{\"id\":\"b6d24b8e-af0b-4c3c-be0c-359bbd97381e\",\"subscription\":\"opt_in\"}]" } } }, "CreateContactImportResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact_import" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created contact import.", "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, "ContactImportCounts": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of rows processed by the import.", "example": 100 }, "created": { "type": "integer", "description": "Number of contacts created by the import.", "example": 80 }, "updated": { "type": "integer", "description": "Number of contacts updated by the import.", "example": 10 }, "skipped": { "type": "integer", "description": "Number of rows skipped by the import.", "example": 5 }, "failed": { "type": "integer", "description": "Number of rows that failed during the import.", "example": 5 } } }, "ContactImport": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact_import" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the contact import.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Current status of the contact import.", "example": "completed" }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact import was created.", "example": "2023-10-06 23:47:56.678+00" }, "completed_at": { "type": [ "string", "null" ], "description": "Timestamp indicating when the contact import completed.", "example": "2023-10-06 23:50:56.678+00" }, "counts": { "$ref": "#/components/schemas/ContactImportCounts" } } }, "GetContactImportResponseSuccess": { "allOf": [ { "$ref": "#/components/schemas/ContactImport" } ] }, "ListContactImportsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing contact imports.", "items": { "$ref": "#/components/schemas/ContactImport" } } } }, "CreateBroadcastOptions": { "type": "object", "required": [ "from", "subject", "segment_id" ], "properties": { "name": { "type": "string", "description": "Name of the broadcast." }, "segment_id": { "type": "string", "description": "Unique identifier of the segment this broadcast will be sent to." }, "audience_id": { "type": "string", "description": "Use `segment_id` instead. Unique identifier of the segment this broadcast will be sent to.", "deprecated": true }, "from": { "type": "string", "description": "The email address of the sender." }, "subject": { "type": "string", "description": "The subject line of the email." }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "The email addresses to which replies should be sent." }, "preview_text": { "type": "string", "description": "The preview text of the email.", "example": "Here are our announcements" }, "html": { "type": "string", "description": "The HTML version of the message." }, "text": { "type": "string", "description": "The plain text version of the message." }, "topic_id": { "type": "string", "description": "The topic ID that the broadcast will be scoped to." }, "send": { "type": "boolean", "description": "Whether to send the broadcast immediately or keep it as a draft.\n" }, "scheduled_at": { "type": "string", "description": "Schedule time to send the broadcast. Can only be used if `send` is true.\n" } } }, "CreateBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the broadcast.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "broadcast" } } }, "ListBroadcastsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing broadcast information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the broadcast.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "name": { "type": "string", "description": "Name of the broadcast.", "example": "November announcements" }, "audience_id": { "type": "string", "description": "Deprecated. Use segment_id instead.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "deprecated": true }, "segment_id": { "type": "string", "description": "Unique identifier of the segment this broadcast will be sent to.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "status": { "type": "string", "description": "The status of the broadcast.", "example": "draft" }, "created_at": { "type": "string", "description": "Timestamp indicating when the broadcast was created.", "example": "2023-10-06 22:59:55.977+00" }, "scheduled_at": { "type": "string", "description": "Timestamp indicating when the broadcast is scheduled to be sent.", "example": "2023-10-06 22:59:55.977+00" }, "sent_at": { "type": "string", "description": "Timestamp indicating when the broadcast was sent.", "example": "2023-10-06 22:59:55.977+00" }, "topic_id": { "type": "string", "description": "The topic ID that the broadcast is scoped to.", "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" } } } } } }, "GetBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the broadcast.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "name": { "type": "string", "description": "Name of the broadcast.", "example": "November announcements" }, "audience_id": { "type": [ "string", "null" ], "description": "Deprecated: use `segment_id` instead. Unique identifier of the segment this broadcast will be sent to.", "deprecated": true }, "segment_id": { "type": [ "string", "null" ], "description": "Unique identifier of the segment this broadcast will be sent to." }, "from": { "type": "string", "description": "The email address of the sender.", "example": "Acme " }, "subject": { "type": "string", "description": "The subject line of the email.", "example": "Hello World" }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "The email addresses to which replies should be sent." }, "preview_text": { "type": "string", "description": "The preview text of the email.", "example": "Here are our announcements" }, "status": { "type": "string", "description": "The status of the broadcast.", "example": "draft" }, "created_at": { "type": "string", "description": "Timestamp indicating when the broadcast was created.", "example": "2023-10-06 22:59:55.977+00" }, "scheduled_at": { "type": "string", "description": "Timestamp indicating when the broadcast is scheduled to be sent.", "example": "2023-10-06 22:59:55.977+00" }, "sent_at": { "type": "string", "description": "Timestamp indicating when the broadcast was sent.", "example": "2023-10-06 22:59:55.977+00" }, "text": { "type": [ "string", "null" ], "description": "The plain text version of the broadcast content.", "example": "Hello {{{FIRST_NAME|there}}}!" }, "html": { "type": [ "string", "null" ], "description": "The HTML version of the broadcast content.", "example": "

Hello {{{FIRST_NAME|there}}}!

" }, "topic_id": { "type": [ "string", "null" ], "description": "The topic ID that the broadcast is scoped to.", "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" } } }, "UpdateBroadcastOptions": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the broadcast." }, "audience_id": { "type": "string", "description": "Use `segment_id` instead. Unique identifier of the audience this broadcast will be sent to.", "deprecated": true }, "segment_id": { "type": "string", "description": "Unique identifier of the segment this broadcast will be sent to." }, "from": { "type": "string", "description": "The email address of the sender." }, "subject": { "type": "string", "description": "The subject line of the email." }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "The email addresses to which replies should be sent." }, "preview_text": { "type": "string", "description": "The preview text of the email." }, "html": { "type": "string", "description": "The HTML version of the message." }, "text": { "type": "string", "description": "The plain text version of the message." }, "topic_id": { "type": "string", "description": "The topic ID that the broadcast will be scoped to." } } }, "UpdateBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the broadcast.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "broadcast" } } }, "RemoveBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the broadcast.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "Type of the response object.", "example": "broadcast" }, "deleted": { "type": "boolean", "description": "The deleted attribute indicates that the corresponding broadcast has been deleted.", "example": true } } }, "SendBroadcastOptions": { "type": "object", "properties": { "scheduled_at": { "type": "string", "description": "Schedule email to be sent later. The date should be in ISO 8601 format." } } }, "SendBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the broadcast.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" } } }, "CancelBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the broadcast.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "broadcast" } } }, "DuplicateBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the duplicated broadcast.", "example": "1f85ae38-f5b9-4c1f-8766-667a53970fea" }, "object": { "type": "string", "description": "The object type of the response.", "example": "broadcast" } } }, "ListBroadcastRecipientsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing broadcast recipients.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque cursor identifying this row, used for pagination.", "example": "b2Zmc2V0OjA" }, "contact_id": { "type": [ "string", "null" ], "description": "The ID of the contact associated with this recipient, if one exists.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "The recipient's email address.", "example": "steve.wozniak@gmail.com" }, "count": { "type": "integer", "description": "The number of times this recipient triggered the event. Only present when `type` is `opened` or `clicked`.", "example": 3 }, "bounce_type": { "type": "string", "enum": [ "permanent", "transient", "undetermined" ], "description": "The type of bounce. Only present when `type` is `bounced`." }, "clicked_links": { "type": "array", "description": "The links this recipient clicked. Only present when `type` is `clicked`.", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The clicked URL.", "example": "https://resend.com/pricing" }, "clicks": { "type": "integer", "description": "The number of times this recipient clicked this URL.", "example": 2 } } } } } } } } }, "ListBroadcastClickedLinksResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing the broadcast's clicked links.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "An opaque cursor for this row, used only for pagination. It does not identify any entity in Resend.", "example": "b2Zmc2V0OjA" }, "url": { "type": "string", "description": "The URL that was clicked.", "example": "https://resend.com/pricing" }, "clicks": { "type": "integer", "description": "Total number of clicks on this URL.", "example": 42 }, "unique_clicks": { "type": "integer", "description": "Number of unique clicks on this URL.", "example": 30 } } } } } }, "RetrievedAttachment": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "attachment" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment.", "example": "660e8400-e29b-41d4-a716-446655440000" }, "filename": { "type": [ "string", "null" ], "description": "The filename of the attachment.", "example": "document.pdf" }, "content_type": { "type": "string", "description": "The MIME type of the attachment.", "example": "application/pdf" }, "content_id": { "type": "string", "description": "The content ID for inline attachments.", "example": "img001" }, "content_disposition": { "type": [ "string", "null" ], "enum": [ "inline", "attachment", null ], "description": "How the attachment should be displayed.", "example": "attachment" }, "download_url": { "type": "string", "description": "Signed URL to download the attachment content.", "example": "https://cloudfront.example.com/path?Signature=..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires.", "example": "2024-10-27T18:30:00.000Z" }, "size": { "type": "integer", "description": "Size of the attachment in bytes.", "example": 2048 } } }, "ListAttachmentsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing attachment information.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment.", "example": "660e8400-e29b-41d4-a716-446655440000" }, "filename": { "type": [ "string", "null" ], "description": "The filename of the attachment.", "example": "document.pdf" }, "content_type": { "type": "string", "description": "The MIME type of the attachment.", "example": "application/pdf" }, "content_id": { "type": "string", "description": "The content ID for inline attachments.", "example": "img001" }, "content_disposition": { "type": [ "string", "null" ], "enum": [ "inline", "attachment", null ], "description": "How the attachment should be displayed.", "example": "attachment" }, "download_url": { "type": "string", "description": "Signed URL to download the attachment content.", "example": "https://cloudfront.example.com/path?Signature=..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires.", "example": "2024-10-27T18:30:00.000Z" }, "size": { "type": "integer", "description": "Size of the attachment in bytes.", "example": 2048 } } } } } }, "GetReceivedEmailResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "email" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the received email.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "to": { "type": "array", "items": { "type": "string" }, "description": "The recipient email addresses.", "example": [ "delivered@resend.dev" ] }, "from": { "type": "string", "description": "The sender email address.", "example": "sender@example.com" }, "subject": { "type": "string", "description": "The email subject.", "example": "Hello World" }, "message_id": { "type": "string", "description": "The unique message ID from the email headers.", "example": "" }, "bcc": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The BCC recipients.", "example": [] }, "cc": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The CC recipients.", "example": [] }, "reply_to": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The reply-to addresses.", "example": [] }, "received_for": { "type": "array", "items": { "type": "string" }, "description": "The recipient addresses the email was forwarded for, taken from the `for` clause of the message's `Received` headers.", "example": [ "forwarded@example.com" ] }, "html": { "type": [ "string", "null" ], "description": "The HTML content of the email.", "example": "

Email content

" }, "text": { "type": [ "string", "null" ], "description": "The plain text content of the email.", "example": "Email content" }, "headers": { "type": [ "object", "null" ], "description": "The email headers.", "example": { "X-Custom-Header": "value" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was received.", "example": "2023-10-06T23:47:56.678Z" }, "attachments": { "type": "array", "description": "Array of attachments.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment." }, "filename": { "type": [ "string", "null" ], "description": "The filename of the attachment." }, "content_type": { "type": "string", "description": "The MIME type of the attachment." }, "content_id": { "type": "string", "description": "The content ID for inline attachments." }, "content_disposition": { "type": [ "string", "null" ], "enum": [ "inline", "attachment", null ], "description": "How the attachment should be displayed." }, "size": { "type": "integer", "description": "Size of the attachment in bytes." } } } } } }, "ListReceivedEmailsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing received email information.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the received email.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "to": { "type": "array", "items": { "type": "string" }, "description": "The recipient email addresses.", "example": [ "delivered@resend.dev" ] }, "from": { "type": "string", "description": "The sender email address.", "example": "sender@example.com" }, "subject": { "type": [ "string", "null" ], "description": "The email subject.", "example": "Hello World" }, "message_id": { "type": "string", "description": "The unique message ID from the email headers.", "example": "" }, "bcc": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The BCC recipients." }, "cc": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The CC recipients." }, "reply_to": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The reply-to addresses." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was received.", "example": "2023-10-06T23:47:56.678Z" }, "attachments": { "type": "array", "description": "Array of attachments for this email.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment." }, "filename": { "type": [ "string", "null" ], "description": "The filename of the attachment." }, "content_type": { "type": "string", "description": "The MIME type of the attachment." }, "content_id": { "type": "string", "description": "The content ID for inline attachments." }, "content_disposition": { "type": [ "string", "null" ], "enum": [ "inline", "attachment", null ], "description": "How the attachment should be displayed." }, "size": { "type": "integer", "description": "Size of the attachment in bytes." } } } } } } } } }, "CreateWebhookRequest": { "type": "object", "required": [ "endpoint", "events" ], "properties": { "endpoint": { "type": "string", "description": "The URL where webhook events will be sent.", "example": "https://webhook.example.com/handler" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of event types to subscribe to.", "example": [ "email.sent", "email.delivered", "email.bounced", "email.suppressed" ] } } }, "CreateWebhookResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "signing_secret": { "type": "string", "description": "The secret key used to verify webhook payloads.", "example": "whsec_..." } } }, "GetWebhookResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "endpoint": { "type": "string", "description": "The URL where webhook events are sent.", "example": "https://webhook.example.com/handler" }, "events": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of event types subscribed to.", "example": [ "email.sent", "email.delivered" ] }, "status": { "type": "string", "description": "The status of the webhook.", "example": "enabled" }, "created_at": { "type": "string", "description": "Timestamp indicating when the webhook was created.", "example": "2023-10-06 23:47:56.678+00" }, "signing_secret": { "type": "string", "description": "The secret key used to verify webhook payloads.", "example": "whsec_..." } } }, "ListWebhooksResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing webhook information.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "endpoint": { "type": "string", "description": "The URL where webhook events are sent.", "example": "https://webhook.example.com/handler" }, "events": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of event types subscribed to.", "example": [ "email.sent" ] }, "status": { "type": "string", "description": "The status of the webhook.", "example": "enabled" }, "created_at": { "type": "string", "description": "Timestamp indicating when the webhook was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "endpoint": { "type": "string", "description": "The URL where webhook events will be sent.", "example": "https://webhook.example.com/new-handler" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of event types to subscribe to.", "example": [ "email.sent", "email.delivered" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "The status of the webhook.", "example": "enabled" } } }, "UpdateWebhookResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the updated webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, "RotateWebhookSigningSecretResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "signing_secret": { "type": "string", "description": "The new secret key used to verify webhook payloads.", "example": "whsec_..." } } }, "DeleteWebhookResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the deleted webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "deleted": { "type": "boolean", "description": "Indicates whether the webhook was successfully deleted.", "example": true } } }, "ListWebhookEventsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing webhook event information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the webhook event.", "example": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2" }, "type": { "type": "string", "description": "The type of the event.", "example": "email.sent" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the event was created.", "example": "2026-08-22T15:28:00.000Z" }, "status": { "type": "string", "enum": [ "pending", "attempting", "success", "failed" ], "description": "The delivery status of the event for this webhook.", "example": "success" } } } } } }, "GetWebhookEventResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook_event" }, "id": { "type": "string", "description": "The ID of the webhook event.", "example": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2" }, "type": { "type": "string", "description": "The type of the event.", "example": "email.sent" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the event was created.", "example": "2026-08-22T15:28:00.000Z" }, "status": { "type": "string", "enum": [ "pending", "attempting", "success", "failed" ], "description": "The delivery status of the event for this webhook.", "example": "attempting" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the next scheduled delivery attempt, or null when none is scheduled. Always null once the event has succeeded or permanently failed.", "example": "2026-08-22T15:33:00.000Z" }, "payload": { "type": "object", "description": "The event payload sent to the webhook endpoint.", "example": { "type": "email.sent", "created_at": "2026-08-22T15:28:00.000Z", "data": { "email_id": "571f1f42-1c2d-4b1f-8f8e-8b3b5b3b5b3b", "from": "onboarding@resend.dev", "to": [ "delivered@resend.dev" ], "subject": "Welcome", "created_at": "2026-08-22T15:27:59.000Z" } } } } }, "ListWebhookEventAttemptsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing webhook event attempt information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the webhook event attempt.", "example": "atmpt_1srOrx2ZWZBpBUvZwXKQmoEYga2" }, "http_status_code": { "type": "integer", "description": "The HTTP status code returned by the webhook endpoint.", "example": 200 }, "response": { "type": "string", "description": "The response body returned by the webhook endpoint.", "example": "{\"ok\":true}" }, "sent_at": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the attempt was sent.", "example": "2026-08-22T15:33:12.000Z" } } } } } }, "ReplayWebhookEventResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "webhook_event" }, "id": { "type": "string", "description": "The ID of the replayed webhook event.", "example": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2" } } }, "TemplateVariable": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template variable." }, "key": { "type": "string", "description": "The key of the variable." }, "type": { "type": "string", "description": "The type of the variable.", "enum": [ "string", "number", "boolean", "object", "list" ] }, "fallback_value": { "description": "The fallback value of the variable.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": {} } ] }, "created_at": { "type": "string", "description": "Timestamp indicating when the variable was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "Timestamp indicating when the variable was last updated.", "example": "2023-10-06 23:47:56.678+00" } }, "required": [ "key", "type" ] }, "TemplateVariableInput": { "type": "object", "properties": { "key": { "type": "string", "description": "The key of the variable." }, "type": { "type": "string", "description": "The type of the variable.", "enum": [ "string", "number", "boolean", "object", "list" ] }, "fallback_value": { "description": "The fallback value of the variable.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": {} } ] } }, "required": [ "key", "type" ] }, "Template": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "template" }, "id": { "type": "string", "description": "The ID of the template." }, "current_version_id": { "type": "string", "description": "The ID of the current version of the template." }, "name": { "type": "string", "description": "The name of the template." }, "alias": { "type": "string", "description": "The alias of the template." }, "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, "subject": { "type": "string", "description": "Email subject." }, "reply_to": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Reply-to email addresses." }, "html": { "type": "string", "description": "The HTML version of the template." }, "text": { "type": "string", "description": "The plain text version of the template." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } }, "created_at": { "type": "string", "description": "Timestamp indicating when the template was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "Timestamp indicating when the template was last updated.", "example": "2023-10-06 23:47:56.678+00" }, "status": { "type": "string", "description": "The publication status of the template.", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "description": "Timestamp indicating when the template was published.", "example": "2023-10-06 23:47:56.678+00" }, "has_unpublished_versions": { "type": "boolean", "description": "Indicates whether the template has unpublished versions." } } }, "TemplateListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "name": { "type": "string", "description": "The name of the template." }, "status": { "type": "string", "description": "The publication status of the template.", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "description": "Timestamp indicating when the template was published.", "example": "2023-10-06 23:47:56.678+00" }, "created_at": { "type": "string", "description": "Timestamp indicating when the template was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "Timestamp indicating when the template was last updated.", "example": "2023-10-06 23:47:56.678+00" }, "alias": { "type": "string", "description": "The alias of the template." } } }, "CreateTemplateRequest": { "type": "object", "required": [ "name", "html" ], "properties": { "name": { "type": "string", "description": "The name of the template." }, "alias": { "type": "string", "description": "The alias of the template." }, "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, "subject": { "type": "string", "description": "Email subject." }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "Reply-to email addresses." }, "html": { "type": "string", "description": "The HTML version of the template." }, "text": { "type": "string", "description": "The plain text version of the template." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariableInput" } } } }, "CreateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "ListTemplatesResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "Array containing templates information.", "items": { "$ref": "#/components/schemas/TemplateListItem" } }, "has_more": { "type": "boolean", "description": "Indicates if there are more templates to retrieve." } } }, "UpdateTemplateOptions": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the template." }, "alias": { "type": "string", "description": "The alias of the template." }, "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, "subject": { "type": "string", "description": "Email subject." }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "Reply-to email addresses." }, "html": { "type": "string", "description": "The HTML version of the template." }, "text": { "type": "string", "description": "The plain text version of the template." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariableInput" } } } }, "UpdateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "RemoveTemplateResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "template" }, "id": { "type": "string", "description": "The ID of the template." }, "deleted": { "type": "boolean", "description": "Indicates whether the template was successfully deleted.", "example": true } } }, "PublishTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "DuplicateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the duplicated template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "CreateSegmentOptions": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the segment." }, "audience_id": { "type": "string", "description": "The ID of the audience this segment belongs to.", "deprecated": true }, "filter": { "type": "object", "description": "Filter conditions for the segment." } } }, "CreateSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "segment" } } }, "GetSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "segment" }, "name": { "type": "string", "description": "The name of the segment.", "example": "Active Users" }, "audience_id": { "type": "string", "description": "The ID of the audience this segment belongs to.", "deprecated": true }, "filter": { "type": "object", "description": "Filter conditions for the segment." }, "created_at": { "type": "string", "description": "Timestamp indicating when the segment was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "UpdateSegmentOptions": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the segment." } } }, "UpdateSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "segment" } } }, "ListSegmentsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing segment information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the segment." }, "name": { "type": "string", "description": "Name of the segment." }, "audience_id": { "type": "string", "description": "The ID of the audience this segment belongs to.", "deprecated": true }, "created_at": { "type": "string", "description": "Timestamp indicating when the segment was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "RemoveSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "segment" }, "deleted": { "type": "boolean", "description": "Indicates whether the segment was successfully deleted.", "example": true } } }, "CreateTopicOptions": { "type": "object", "required": [ "name", "default_subscription" ], "properties": { "name": { "type": "string", "description": "The name of the topic. Max 50 characters.", "maxLength": 50 }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic. Cannot be changed after creation." }, "description": { "type": "string", "description": "A description of the topic. Max 200 characters.", "maxLength": 200 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "default": "private", "description": "The visibility of the topic. Public topics are visible to all contacts on the unsubscribe page. Private topics are only visible to opted-in contacts." } } }, "CreateTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "topic" } } }, "GetTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "topic" }, "name": { "type": "string", "description": "The name of the topic.", "example": "Newsletter" }, "description": { "type": "string", "description": "A description of the topic." }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the topic." }, "created_at": { "type": "string", "description": "Timestamp indicating when the topic was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "ListTopicsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing topic information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "name": { "type": "string", "description": "Name of the topic." }, "description": { "type": "string", "description": "A description of the topic." }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the topic." }, "created_at": { "type": "string", "description": "Timestamp indicating when the topic was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "UpdateTopicOptions": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the topic. Max 50 characters.", "maxLength": 50 }, "description": { "type": "string", "description": "A description of the topic. Max 200 characters.", "maxLength": 200 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the topic." } } }, "UpdateTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "topic" } } }, "RemoveTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "topic" }, "deleted": { "type": "boolean", "description": "Indicates whether the topic was successfully deleted.", "example": true } } }, "CreateContactPropertyOptions": { "type": "object", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "description": "The property key. Max length is 50 characters. Only alphanumeric characters and underscores are allowed." }, "type": { "type": "string", "enum": [ "string", "number" ], "description": "The property type." }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "The default value to use when the property is not set for a contact. Must match the type specified in the type field." } } }, "CreateContactPropertyResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact property.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "contact_property" } } }, "GetContactPropertyResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_property" }, "id": { "type": "string", "description": "The ID of the contact property.", "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" }, "key": { "type": "string", "description": "The property key.", "example": "company_name" }, "type": { "type": "string", "description": "The property type.", "example": "string" }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "The default value when the property is not set for a contact.", "example": "Acme Corp" }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact property was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "ListContactPropertiesResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing contact property information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the contact property." }, "key": { "type": "string", "description": "The property key." }, "type": { "type": "string", "description": "The property type." }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "The default value when the property is not set for a contact." }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact property was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "UpdateContactPropertyOptions": { "type": "object", "properties": { "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "The default value to use when the property is not set for a contact. Must match the type of the property." } } }, "UpdateContactPropertyResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact property.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "contact_property" } } }, "RemoveContactPropertyResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact property.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "contact_property" }, "deleted": { "type": "boolean", "description": "Indicates whether the contact property was successfully deleted.", "example": true } } }, "AddContactToSegmentResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_segment" }, "contact_id": { "type": "string", "description": "The ID of the contact." }, "segment_id": { "type": "string", "description": "The ID of the segment." } } }, "ListContactSegmentsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing segment information for this contact.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the segment." }, "name": { "type": "string", "description": "Name of the segment." }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact was added to the segment.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "RemoveContactFromSegmentResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_segment" }, "contact_id": { "type": "string", "description": "The ID of the contact." }, "segment_id": { "type": "string", "description": "The ID of the segment." }, "deleted": { "type": "boolean", "description": "Indicates whether the contact was successfully removed from the segment.", "example": true } } }, "GetContactTopicsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing topic subscriptions for this contact.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "name": { "type": "string", "description": "Name of the topic." }, "description": { "type": "string", "description": "Description of the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status for this topic." } } } } } }, "UpdateContactTopicsOptions": { "type": "object", "required": [ "topics" ], "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status (opt_in or opt_out)." } } } } } }, "UpdateContactTopicsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_topics" }, "contact_id": { "type": "string", "description": "The ID of the contact." }, "topics": { "type": "array", "description": "Array of updated topic subscriptions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status." } } } } } }, "LogSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The log ID." }, "created_at": { "type": "string", "description": "The date the log was created.", "example": "2023-10-06 23:47:56.678+00" }, "endpoint": { "type": "string", "description": "The API endpoint that was called." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS" ], "description": "The HTTP method used." }, "response_status": { "type": "integer", "description": "The HTTP status code of the response." }, "user_agent": { "type": [ "string", "null" ], "description": "The user agent of the request." } } }, "Log": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "log" }, "id": { "type": "string", "format": "uuid", "description": "The log ID." }, "created_at": { "type": "string", "description": "The date the log was created.", "example": "2023-10-06 23:47:56.678+00" }, "endpoint": { "type": "string", "description": "The API endpoint that was called." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS" ], "description": "The HTTP method used." }, "response_status": { "type": "integer", "description": "The HTTP status code of the response." }, "user_agent": { "type": [ "string", "null" ], "description": "The user agent of the request." }, "request_body": { "type": [ "object", "null" ], "description": "The request body sent to the API." }, "response_body": { "type": [ "object", "null" ], "description": "The response body returned by the API." } } }, "ListLogsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing log information.", "items": { "$ref": "#/components/schemas/LogSummary" } } } }, "AutomationStep": { "type": "object", "description": "A step in an automation workflow. The `config` object varies based on the step `type`.", "required": [ "key", "type", "config" ], "properties": { "key": { "type": "string", "description": "A unique key for this step within the automation graph." }, "type": { "type": "string", "enum": [ "trigger", "send_email", "delay", "wait_for_event", "condition", "contact_update", "contact_delete", "add_to_segment" ], "description": "The type of automation step." }, "config": { "type": "object", "description": "Configuration for the step. Shape depends on `type`: - **trigger**: `{ event_name: string }` - **send_email**: `{ template: { id: string, variables?: object }, subject?: string, from?: string, reply_to?: string }` - **delay**: `{ duration: string }` — a human-readable duration (e.g. `\"30 minutes\"`) - **wait_for_event**: `{ event_name: string, timeout?: string, filter_rule?: object }` — `timeout` is a human-readable duration (e.g. `\"1 hour\"`) - **condition**: A rule tree with `type` (`rule`, `and`, `or`), `field`, `operator`, and `value` - **contact_update**: `{ first_name?: string|object, last_name?: string|object, unsubscribed?: boolean|object, properties?: object }` - **contact_delete**: `{}` - **add_to_segment**: `{ segment_id: string }`\n" } } }, "AutomationStepResponse": { "type": "object", "description": "A step as returned when retrieving an automation.", "properties": { "key": { "type": "string", "description": "The unique key of this step within the automation graph." }, "type": { "type": "string", "enum": [ "trigger", "send_email", "delay", "wait_for_event", "condition", "contact_update", "contact_delete", "add_to_segment" ], "description": "The type of automation step." }, "config": { "type": "object", "description": "Configuration for the step. Shape depends on `type`. For `delay` steps, config contains `{ duration: string }` with a human-readable duration (e.g. `\"30 minutes\"`). For `wait_for_event` steps, config contains `{ event_name: string, timeout?: string, filter_rule?: object }` where `timeout` is a human-readable duration.\n" } } }, "AutomationConnection": { "type": "object", "description": "A connection between two steps in the automation graph.", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "description": "The `key` of the source step." }, "to": { "type": "string", "description": "The `key` of the target step." }, "type": { "type": "string", "enum": [ "default", "condition_met", "condition_not_met", "timeout", "event_received" ], "default": "default", "description": "The type of connection. Defaults to `default`." } } }, "CreateAutomationRequest": { "type": "object", "required": [ "name", "steps", "connections" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the automation." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "The initial status of the automation. Defaults to `disabled`." }, "steps": { "type": "array", "minItems": 1, "maxItems": 150, "description": "The steps that compose the automation workflow. Must include at least one `trigger` step.", "items": { "$ref": "#/components/schemas/AutomationStep" } }, "connections": { "type": "array", "description": "The connections between steps in the automation graph.", "items": { "$ref": "#/components/schemas/AutomationConnection" } } } }, "CreateAutomationResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation" }, "id": { "type": "string", "description": "The ID of the created automation." } } }, "Automation": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation" }, "id": { "type": "string", "description": "The ID of the automation." }, "name": { "type": "string", "description": "The name of the automation." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "The current status of the automation." }, "created_at": { "type": "string", "description": "The date and time the automation was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "The date and time the automation was last updated.", "example": "2023-10-06 23:47:56.678+00" }, "steps": { "type": "array", "description": "The steps in the active version of the automation.", "items": { "$ref": "#/components/schemas/AutomationStepResponse" } }, "connections": { "type": "array", "description": "The connections between steps in the active version of the automation.", "items": { "$ref": "#/components/schemas/AutomationConnection" } } } }, "AutomationListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the automation." }, "name": { "type": "string", "description": "The name of the automation." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "The current status of the automation." }, "created_at": { "type": "string", "description": "The date and time the automation was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "The date and time the automation was last updated.", "example": "2023-10-06 23:47:56.678+00" } } }, "ListAutomationsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array of automations.", "items": { "$ref": "#/components/schemas/AutomationListItem" } } } }, "PatchAutomationRequest": { "type": "object", "description": "At least one of `name`, `status`, or `steps` and `connections` must be provided. When updating the workflow graph, both `steps` and `connections` must be provided together.\n", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the automation." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "The status of the automation." }, "steps": { "type": "array", "minItems": 1, "maxItems": 150, "description": "The steps that compose the automation workflow. Must be provided together with `connections`.", "items": { "$ref": "#/components/schemas/AutomationStep" } }, "connections": { "type": "array", "description": "The connections between steps in the automation graph. Must be provided together with `steps`.", "items": { "$ref": "#/components/schemas/AutomationConnection" } } } }, "PatchAutomationResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation" }, "id": { "type": "string", "description": "The ID of the updated automation." } } }, "DeleteAutomationResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation" }, "id": { "type": "string", "description": "The ID of the deleted automation." }, "deleted": { "type": "boolean", "description": "Indicates whether the automation was successfully deleted.", "example": true } } }, "DuplicateAutomationResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation" }, "id": { "type": "string", "description": "The ID of the duplicated automation." } } }, "StopAutomationResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation" }, "id": { "type": "string", "description": "The ID of the stopped automation." }, "status": { "type": "string", "description": "The status of the automation after stopping.", "example": "disabled" } } }, "AutomationRunStep": { "type": "object", "description": "A step execution within an automation run.", "properties": { "key": { "type": "string", "description": "The key of the automation step." }, "type": { "type": "string", "enum": [ "trigger", "send_email", "delay", "wait_for_event", "condition", "contact_update", "contact_delete", "add_to_segment" ], "description": "The type of automation step." }, "status": { "type": "string", "description": "The execution status of this step." }, "started_at": { "type": [ "string", "null" ], "description": "The date and time the step started executing.", "example": "2023-10-06 23:47:56.678+00" }, "completed_at": { "type": [ "string", "null" ], "description": "The date and time the step completed executing.", "example": "2023-10-06 23:47:56.678+00" }, "output": { "type": [ "object", "null" ], "description": "The output produced by the step, if any." }, "error": { "type": [ "object", "null" ], "description": "The error produced by the step, if any." }, "created_at": { "type": "string", "description": "The date and time the step record was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "AutomationRun": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "automation_run" }, "id": { "type": "string", "description": "The ID of the automation run." }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled" ], "description": "The current status of the automation run." }, "started_at": { "type": [ "string", "null" ], "description": "The date and time the run started.", "example": "2023-10-06 23:47:56.678+00" }, "completed_at": { "type": [ "string", "null" ], "description": "The date and time the run completed.", "example": "2023-10-06 23:47:56.678+00" }, "created_at": { "type": "string", "description": "The date and time the run was created.", "example": "2023-10-06 23:47:56.678+00" }, "steps": { "type": "array", "description": "The steps executed in this run, sorted in graph order.", "items": { "$ref": "#/components/schemas/AutomationRunStep" } } } }, "AutomationRunListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the automation run." }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled" ], "description": "The current status of the automation run." }, "started_at": { "type": [ "string", "null" ], "description": "The date and time the run started.", "example": "2023-10-06 23:47:56.678+00" }, "completed_at": { "type": [ "string", "null" ], "description": "The date and time the run completed.", "example": "2023-10-06 23:47:56.678+00" }, "created_at": { "type": "string", "description": "The date and time the run was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "ListAutomationRunsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array of automation runs.", "items": { "$ref": "#/components/schemas/AutomationRunListItem" } } } }, "Event": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "event" }, "id": { "type": "string", "format": "uuid", "description": "The event ID." }, "name": { "type": "string", "description": "The event name." }, "schema": { "type": [ "object", "null" ], "description": "A flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." }, "created_at": { "type": "string", "description": "The date and time the event was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": [ "string", "null" ], "description": "The date and time the event was last updated.", "example": "2023-10-06 23:47:56.678+00" } } }, "EventSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The event ID." }, "name": { "type": "string", "description": "The event name." }, "schema": { "type": [ "object", "null" ], "description": "A flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." }, "created_at": { "type": "string", "description": "The date and time the event was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": [ "string", "null" ], "description": "The date and time the event was last updated.", "example": "2023-10-06 23:47:56.678+00" } } }, "CreateEventRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the event. Cannot start with the reserved `resend:` prefix." }, "schema": { "type": [ "object", "null" ], "description": "An optional flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." } } }, "CreateEventResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "event" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the created event." } } }, "ListEventsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing event information.", "items": { "$ref": "#/components/schemas/EventSummary" } } } }, "UpdateEventRequest": { "type": "object", "required": [ "schema" ], "properties": { "schema": { "type": [ "object", "null" ], "description": "A flat key/type map defining the event payload schema. Set to `null` to clear the schema. Supported types are `string`, `number`, `boolean`, and `date`." } } }, "UpdateEventResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "event" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the updated event." } } }, "RemoveEventResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "event" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the deleted event." }, "deleted": { "type": "boolean", "description": "Indicates whether the event was deleted.", "example": true } } }, "SendEventRequest": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The name of the event to send." }, "contact_id": { "type": "string", "format": "uuid", "description": "The ID of the contact to associate with this event. Exactly one of `contact_id` or `email` must be provided." }, "email": { "type": "string", "format": "email", "description": "The email address to associate with this event. Exactly one of `contact_id` or `email` must be provided." }, "payload": { "type": "object", "additionalProperties": true, "description": "An optional payload of key/value pairs to include with the event." } } }, "SendEventResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "event" }, "event": { "type": "string", "description": "The name of the event that was sent." } } }, "WebhookEventBounce": { "type": "object", "required": [ "diagnosticCode", "message", "subType", "type" ], "properties": { "diagnosticCode": { "type": "array", "items": { "type": "string" }, "description": "Array of SMTP diagnostic responses from the receiving server, one entry per recipient (e.g., `smtp; 550 5.1.1 user unknown`)." }, "message": { "type": "string", "description": "Detailed bounce message describing why the email bounced." }, "subType": { "type": "string", "enum": [ "Undetermined", "General", "NoEmail", "MailboxFull", "MessageTooLarge", "ContentRejected", "AttachmentRejected" ], "description": "Bounce sub-type." }, "type": { "type": "string", "enum": [ "Undetermined", "Transient", "Permanent" ], "description": "Bounce type." } } }, "WebhookEventClick": { "type": "object", "required": [ "ipAddress", "link", "timestamp", "userAgent" ], "properties": { "ipAddress": { "type": "string", "description": "IP address of the user who clicked the link." }, "link": { "type": "string", "description": "The URL that was clicked." }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the click occurred.", "example": "2023-10-06T23:47:56.678Z" }, "userAgent": { "type": "string", "description": "User agent string of the browser that clicked the link." } } }, "WebhookEventFailed": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Reason for the email failure (e.g., `reached_daily_quota`)." } } }, "WebhookEventSuppressed": { "type": "object", "required": [ "diagnosticCode", "message", "reason", "type" ], "properties": { "diagnosticCode": { "type": "array", "items": { "type": "string" }, "description": "Array of SMTP diagnostic responses from the receiving server, one entry per recipient." }, "message": { "type": "string", "description": "Detailed suppression message describing why the email was suppressed." }, "reason": { "type": "string", "enum": [ "previous_bounce", "previous_complaint" ], "description": "Reason the address is suppressed." }, "type": { "type": "string", "enum": [ "Suppressed", "OnAccountSuppressionList" ], "description": "Suppression type." } } }, "WebhookEventAttachment": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the attachment." }, "filename": { "type": "string", "description": "The filename of the attachment." }, "content_type": { "type": "string", "description": "The MIME type of the attachment." }, "content_disposition": { "type": "string", "description": "The content disposition (e.g., `inline` or `attachment`)." }, "content_id": { "type": "string", "description": "Content-ID header used for referencing inline images." } } }, "WebhookDomainRecord": { "type": "object", "required": [ "record", "name", "value", "type", "ttl", "status" ], "properties": { "record": { "type": "string", "enum": [ "SPF", "DKIM", "Receiving MX", "Tracking", "TrackingCAA" ], "description": "The purpose of the DNS record (SPF and DKIM for sending; Receiving MX for inbound emails; Tracking and TrackingCAA for click and open tracking)." }, "name": { "type": "string", "description": "DNS record name or subdomain." }, "value": { "type": "string", "description": "DNS record value to be set." }, "type": { "type": "string", "enum": [ "MX", "TXT", "CNAME", "CAA" ], "description": "DNS record type." }, "ttl": { "type": "string", "description": "Time to live for the DNS record (e.g., `Auto`, `60`)." }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "temporary_failure", "not_started" ], "description": "Verification status of this specific record." }, "priority": { "type": "integer", "description": "Priority value (only applicable for MX records)." } } }, "OutboundEmailEventData": { "type": "object", "required": [ "email_id", "created_at", "from", "to", "subject" ], "properties": { "email_id": { "type": "string", "description": "Unique identifier for the email." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was created.", "example": "2023-10-06T23:47:56.678Z" }, "from": { "type": "string", "description": "Sender email address and name in the format `Name `." }, "to": { "type": "array", "items": { "type": "string" }, "description": "Array of impacted recipient email addresses." }, "subject": { "type": "string", "description": "Email subject line." }, "broadcast_id": { "type": "string", "description": "Unique identifier for the broadcast campaign, if applicable." }, "template_id": { "type": "string", "description": "Unique identifier for the template used, if applicable." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Tag key-value pairs associated with the email." }, "headers": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "description": "Custom headers included with the email (omitted when no custom headers are set)." } } }, "EmailBouncedEventData": { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailEventData" }, { "type": "object", "required": [ "bounce" ], "properties": { "bounce": { "$ref": "#/components/schemas/WebhookEventBounce" } } } ] }, "EmailClickedEventData": { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailEventData" }, { "type": "object", "required": [ "click" ], "properties": { "click": { "$ref": "#/components/schemas/WebhookEventClick" } } } ] }, "EmailFailedEventData": { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailEventData" }, { "type": "object", "required": [ "failed" ], "properties": { "failed": { "$ref": "#/components/schemas/WebhookEventFailed" } } } ] }, "EmailSuppressedEventData": { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailEventData" }, { "type": "object", "required": [ "suppressed" ], "properties": { "suppressed": { "$ref": "#/components/schemas/WebhookEventSuppressed" } } } ] }, "EmailReceivedEventData": { "type": "object", "required": [ "email_id", "created_at", "from", "to", "subject", "message_id", "bcc", "cc", "attachments" ], "properties": { "email_id": { "type": "string", "description": "Unique identifier for the email." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was received.", "example": "2023-10-06T23:47:56.678Z" }, "from": { "type": "string", "description": "Sender email address." }, "to": { "type": "array", "items": { "type": "string" }, "description": "Array of recipient email addresses." }, "subject": { "type": "string", "description": "Email subject line." }, "message_id": { "type": "string", "description": "The unique message ID from the email headers." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipients." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC recipients." }, "received_for": { "type": "array", "items": { "type": "string" }, "description": "The recipient addresses the email was forwarded for, taken from the `for` clause of the message's `Received` headers.", "example": [ "forwarded@example.com" ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventAttachment" }, "description": "Array of attachment metadata." } } }, "ContactEventData": { "type": "object", "required": [ "id", "created_at", "updated_at", "email", "unsubscribed" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the contact." }, "audience_id": { "type": "string", "description": "Unique identifier for the audience this contact belongs to." }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of segment IDs the contact belongs to." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was created.", "example": "2023-10-06T23:47:56.678Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was last updated.", "example": "2023-10-06T23:47:56.678Z" }, "email": { "type": "string", "description": "Contact's email address." }, "first_name": { "type": [ "string", "null" ], "description": "Contact's first name." }, "last_name": { "type": [ "string", "null" ], "description": "Contact's last name." }, "unsubscribed": { "type": "boolean", "description": "Whether the contact has unsubscribed from all emails sent from your team." } } }, "ContactTopicsEventData": { "type": "object", "required": [ "email", "topics" ], "properties": { "email": { "type": "string", "description": "Contact's email address." }, "topics": { "type": "array", "items": { "type": "object", "required": [ "id", "subscription" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The new subscription status for this topic." } } }, "description": "Topics whose subscription changed in this update." } } }, "DomainEventData": { "type": "object", "required": [ "id", "name", "status", "created_at", "region", "records" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the domain." }, "name": { "type": "string", "description": "The domain name (e.g., `example.com`)." }, "status": { "type": "string", "enum": [ "verified", "partially_verified", "partially_failed", "failed", "pending", "not_started" ], "description": "Aggregated verification status of the domain." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the domain was created.", "example": "2023-10-06T23:47:56.678Z" }, "region": { "type": "string", "enum": [ "us-east-1", "eu-west-1", "sa-east-1", "ap-northeast-1" ], "description": "AWS region where the domain is configured." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDomainRecord" }, "description": "DNS records required for domain verification." } } }, "SuppressionEventData": { "type": "object", "required": [ "id", "email", "origin", "source_id", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the suppression." }, "email": { "type": "string", "description": "Email address that is suppressed." }, "origin": { "type": "string", "enum": [ "bounce", "complaint", "manual" ], "description": "Origin of the suppression." }, "source_id": { "type": [ "string", "null" ], "description": "Identifier of the event that caused the suppression, such as the email that bounced or complained. Null for manually added suppressions." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the suppression was created.", "example": "2023-10-06T23:47:56.678Z" } } }, "TopicEventData": { "type": "object", "required": [ "id", "name", "description", "default_subscription", "deleted", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "name": { "type": "string", "description": "The name of the topic." }, "description": { "type": [ "string", "null" ], "description": "A description of the topic." }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic." }, "deleted": { "type": "boolean", "description": "Whether the topic has been deleted." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the topic was created.", "example": "2023-10-06T23:47:56.678Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the topic was last updated.", "example": "2023-10-06T23:47:56.678Z" } } }, "EmailSentEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.sent", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/OutboundEmailEventData" } } }, "EmailDeliveredEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.delivered", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/OutboundEmailEventData" } } }, "EmailDeliveryDelayedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.delivery_delayed", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/OutboundEmailEventData" } } }, "EmailBouncedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.bounced", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/EmailBouncedEventData" } } }, "EmailComplainedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.complained", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/OutboundEmailEventData" } } }, "EmailOpenedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.opened", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/OutboundEmailEventData" } } }, "EmailClickedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.clicked", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/EmailClickedEventData" } } }, "EmailFailedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.failed", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/EmailFailedEventData" } } }, "EmailScheduledEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.scheduled", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/OutboundEmailEventData" } } }, "EmailSuppressedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.suppressed", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/EmailSuppressedEventData" } } }, "EmailReceivedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "email.received", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/EmailReceivedEventData" } } }, "ContactCreatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "contact.created", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/ContactEventData" } } }, "ContactUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "contact.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/ContactEventData" } } }, "ContactDeletedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "contact.deleted", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/ContactEventData" } } }, "ContactTopicsUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "contact.topics.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/ContactTopicsEventData" } } }, "DomainCreatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "domain.created", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/DomainEventData" } } }, "DomainUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "domain.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/DomainEventData" } } }, "DomainDeletedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "domain.deleted", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/DomainEventData" } } }, "SuppressionAddedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "suppression.added", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/SuppressionEventData" } } }, "SuppressionRemovedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "suppression.removed", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/SuppressionEventData" } } }, "TopicCreatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "topic.created", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/TopicEventData" } } }, "TopicUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "topic.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/TopicEventData" } } }, "TopicDeletedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "topic.deleted", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2023-10-06T23:47:56.678Z" }, "data": { "$ref": "#/components/schemas/TopicEventData" } } }, "CreateSuppressionOptions": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address to suppress.", "example": "steve.wozniak@gmail.com" } } }, "CreateSuppressionResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the created suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" } } }, "BatchAddSuppressionsOptions": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "Email addresses to suppress.", "example": [ "steve.wozniak@gmail.com" ] } } }, "BatchAddSuppressionsResponseSuccess": { "type": "object", "properties": { "data": { "type": "array", "description": "Array containing the created suppressions.", "items": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" } } } } } }, "BatchRemoveSuppressionsOptions": { "type": "object", "description": "Provide either `emails` or `ids`, but not both.", "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "Email addresses to remove from the suppression list.", "example": [ "steve.wozniak@gmail.com" ] }, "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "Suppression IDs to remove from the suppression list.", "example": [ "e169aa45-1ecf-4183-9955-b1499d5701d3" ] } } }, "BatchRemoveSuppressionsResponseSuccess": { "type": "object", "properties": { "data": { "type": "array", "description": "Array containing the removed suppressions.", "items": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "deleted": { "type": "boolean", "description": "Indicates whether the suppression was successfully deleted.", "example": true } } } } } }, "RemoveSuppressionResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the removed suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "deleted": { "type": "boolean", "description": "Indicates whether the suppression was successfully deleted.", "example": true } } }, "GetSuppressionResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address that is suppressed.", "example": "steve.wozniak@gmail.com" }, "origin": { "type": "string", "enum": [ "bounce", "complaint", "manual" ], "description": "Origin of the suppression.", "example": "manual" }, "source_id": { "type": [ "string", "null" ], "description": "Identifier of the event that caused the suppression, such as the email that bounced or complained.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "created_at": { "type": "string", "description": "Timestamp indicating when the suppression was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "ListSuppressionsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing suppression information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address that is suppressed.", "example": "steve.wozniak@gmail.com" }, "origin": { "type": "string", "enum": [ "bounce", "complaint", "manual" ], "description": "Origin of the suppression.", "example": "manual" }, "source_id": { "type": [ "string", "null" ], "description": "Identifier of the event that caused the suppression, such as the email that bounced or complained.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "created_at": { "type": "string", "description": "Timestamp indicating when the suppression was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "Inbox": { "type": "object", "required": [ "object", "id", "name", "email_address", "domain_id", "receiving_address", "from_name", "unread", "drafts", "last_received", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "description": "The object type. Always `inbox`.", "example": "inbox" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "name": { "type": "string", "description": "Internal name for the inbox. Recipients do not see it. Falls back to the inbox email address.", "example": "Customer Support" }, "email_address": { "type": "string", "description": "The address of the inbox.", "example": "support@acme.com" }, "domain_id": { "type": "string", "format": "uuid", "description": "The ID of the domain that owns the address.", "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, "receiving_address": { "type": [ "string", "null" ], "description": "The address to forward mail to when forwarding is enabled. `null` otherwise.", "example": null }, "from_name": { "type": [ "string", "null" ], "description": "The name recipients see when mail is sent from this inbox. `null` when not set.", "example": "Ada from Support" }, "unread": { "type": "integer", "description": "The number of unread threads in the Inbox folder.", "example": 3 }, "drafts": { "type": "integer", "description": "The number of unsent drafts.", "example": 2 }, "last_received": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of the newest received email in the Inbox folder. `null` when the folder has no received email.", "example": "2026-08-05T14:03:11.229Z" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the inbox was created.", "example": "2026-08-01T09:12:44.512Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the inbox was last updated.", "example": "2026-08-03T10:20:05.118Z" } } }, "CreateInboxOptions": { "type": "object", "required": [ "email_address" ], "properties": { "email_address": { "type": "string", "description": "The inbox email address on one of your domains. The API trims and lowercases it. The part before the `@` is at most 64 characters and contains only letters, numbers, and `. _ % -`. A `+` returns a 422. It cannot start or end with a dot or contain two dots in a row.", "example": "support@acme.com" }, "name": { "type": "string", "maxLength": 64, "description": "Internal name for the inbox. Recipients do not see it. Max 64 characters. Defaults to `email_address`.", "example": "Customer Support" }, "from_name": { "type": "string", "maxLength": 78, "description": "The name recipients see when mail is sent from this inbox. A plain name, not a `Name ` address. Max 78 characters. It cannot contain a colon, `<`, `>`, line breaks, or other control characters. An email address inside the name must be on a domain the team has verified for sending. An empty string leaves it unset.", "example": "Ada from Support" }, "forwarding": { "type": "boolean", "default": false, "description": "When `true`, Resend provisions a receiving address so you can receive mail without adding an MX record. The address is returned in `receiving_address`." } } }, "CreateInboxResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "inbox" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" } } }, "GetInboxResponseSuccess": { "$ref": "#/components/schemas/Inbox" }, "ListInboxesResponseSuccess": { "type": "object", "required": [ "object", "has_more", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing inbox information.", "items": { "type": "object", "required": [ "id", "name", "email_address", "from_name", "unread", "last_received", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "name": { "type": [ "string", "null" ], "description": "Internal name for the inbox. Recipients do not see it.", "example": "Customer Support" }, "email_address": { "type": "string", "description": "The address of the inbox.", "example": "support@acme.com" }, "from_name": { "type": [ "string", "null" ], "description": "The name recipients see when mail is sent from this inbox. `null` when not set.", "example": "Ada from Support" }, "unread": { "type": "integer", "description": "The number of unread threads in the Inbox folder.", "example": 3 }, "last_received": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of the newest received email in the Inbox folder. `null` when the folder has no received email.", "example": "2026-08-05T14:03:11.229Z" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the inbox was created.", "example": "2026-08-01T09:12:44.512Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the inbox was last updated.", "example": "2026-08-03T10:20:05.118Z" } } } } } }, "UpdateInboxOptions": { "type": "object", "description": "Provide at least one of `name` or `from_name`.", "anyOf": [ { "required": [ "name" ] }, { "required": [ "from_name" ] } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "New internal name for the inbox. Recipients do not see it. Between 1 and 64 characters after trimming.", "example": "Customer Support" }, "from_name": { "type": "string", "maxLength": 78, "description": "The name recipients see when mail is sent from this inbox. A plain name, not a `Name ` address. Max 78 characters. It cannot contain a colon, `<`, `>`, line breaks, or other control characters. An email address inside the name must be on a domain the team has verified for sending. An empty string removes it.", "example": "Ada from Support" } } }, "UpdateInboxResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "The object type.", "example": "inbox" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" } } }, "RemoveInboxResponseSuccess": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string", "description": "The object type.", "example": "inbox" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "deleted": { "type": "boolean", "description": "Indicates whether the inbox was successfully deleted.", "example": true } } }, "InboxAgent": { "type": "object", "required": [ "object", "instructions", "tone", "actions" ], "properties": { "object": { "type": "string", "description": "The object type. Always `inbox_agent`.", "example": "inbox_agent" }, "instructions": { "type": [ "string", "null" ], "description": "Instructions the agent follows when it handles the threads of the inbox. Null when no instructions are set.", "example": "Answer refund questions yourself. Escalate legal threats." }, "tone": { "type": [ "string", "null" ], "enum": [ "concise_professional", "concise_casual", "expanded_professional", "expanded_casual", null ], "description": "The tone the agent writes in. Null when no tone is set.", "example": "concise_professional" }, "actions": { "type": "array", "description": "The actions the agent can take, in the order of the enum. Empty when no actions are enabled.", "items": { "type": "string", "enum": [ "draft_reply", "forward_thread", "add_labels", "assign_thread", "mark_as_spam", "archive", "move_to_trash" ] }, "example": [ "draft_reply", "add_labels" ] } } }, "GetInboxAgentResponseSuccess": { "$ref": "#/components/schemas/InboxAgent" }, "UpdateInboxAgentOptions": { "type": "object", "anyOf": [ { "required": [ "instructions" ] }, { "required": [ "tone" ] }, { "required": [ "actions" ] } ], "description": "At least one of `instructions`, `tone`, or `actions` must be provided. Omitted fields keep their current value.", "properties": { "instructions": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4000, "description": "Instructions the agent follows when it handles the threads of the inbox. Max 4000 characters. Leading and trailing whitespace is trimmed, and the trimmed value must not be empty. Send null to clear the instructions.", "example": "Answer refund questions yourself. Escalate legal threats." }, "tone": { "type": [ "string", "null" ], "enum": [ "concise_professional", "concise_casual", "expanded_professional", "expanded_casual", null ], "description": "The tone the agent writes in. Send null to clear the tone.", "example": "concise_professional" }, "actions": { "type": "array", "description": "The actions the agent can take. Replaces the whole set. Duplicates are removed. Send an empty array to disable all actions. The old names `archive_thread` and `delete_thread` return a 422. Use `archive` and `move_to_trash`.", "items": { "type": "string", "enum": [ "draft_reply", "forward_thread", "add_labels", "assign_thread", "mark_as_spam", "archive", "move_to_trash" ] }, "example": [ "draft_reply", "add_labels" ] } } }, "UpdateInboxAgentResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "The object type. Always `inbox_agent`.", "example": "inbox_agent" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the inbox agent.", "example": "a1f84a4e-6f2b-4f0a-9c1d-8a2e5b3c7d90" } } }, "InboxLabel": { "type": "object", "required": [ "id", "name", "color", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the label.", "example": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" }, "name": { "type": "string", "description": "The name of the label.", "example": "Urgent" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "The color of the label, as a `#RRGGBB` hex color in uppercase.", "example": "#E93D82" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the label was created.", "example": "2026-08-05T14:07:42.881Z" } } }, "ListInboxLabelsResponseSuccess": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "The labels on the inbox, oldest first.", "items": { "$ref": "#/components/schemas/InboxLabel" } } } }, "CreateInboxLabelOptions": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name of the label. Max 64 characters. Leading and trailing whitespace is trimmed. Must not match another label on the inbox, compared without case.", "example": "Urgent" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "The color of the label, as a `#RRGGBB` hex color. It is stored in uppercase. When omitted, a random color from the dashboard palette is used.", "example": "#E93D82" } } }, "CreateInboxLabelResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "inbox_label" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the label.", "example": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" } } }, "UpdateInboxLabelOptions": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A new name for the label. Max 64 characters. Leading and trailing whitespace is trimmed. Must not match another label on the inbox, compared without case.", "example": "Billing" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "A new color for the label, as a `#RRGGBB` hex color. It is stored in uppercase.", "example": "#F76B15" } } }, "UpdateInboxLabelResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "inbox_label" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the updated label.", "example": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" } } }, "RemoveInboxLabelResponseSuccess": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "inbox_label" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the removed label.", "example": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" }, "deleted": { "type": "boolean", "description": "Indicates whether the label was deleted.", "example": true } } }, "InboxThreadLabel": { "type": "object", "required": [ "id", "name", "color" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the label.", "example": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" }, "name": { "type": "string", "description": "The name of the label.", "example": "Urgent" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "The color of the label, as a `#RRGGBB` hex color in uppercase.", "example": "#E93D82" } } }, "InboxThread": { "type": "object", "description": "A thread as it appears in the list of an inbox's threads.", "required": [ "id", "subject", "from", "to", "cc", "bcc", "labels", "email_count", "has_attachment", "has_draft", "read", "received_at", "folder" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12" }, "subject": { "type": [ "string", "null" ], "description": "The subject of the thread.", "example": "Refund for order 1041" }, "from": { "type": [ "string", "null" ], "description": "The sender email address. Can include the display name.", "example": "ada@example.org" }, "to": { "type": "array", "description": "The recipients of the most recent email. For a received email, these are the addresses it was delivered to, not the full `To` header.", "items": { "type": "string" }, "example": [ "support@example.com" ] }, "cc": { "type": "array", "description": "The CC recipients of the most recent email.", "items": { "type": "string" }, "example": [] }, "bcc": { "type": "array", "description": "The BCC recipients of the most recent email. Always empty for a received email.", "items": { "type": "string" }, "example": [] }, "labels": { "type": "array", "description": "The labels attached to the thread.", "items": { "$ref": "#/components/schemas/InboxThreadLabel" } }, "email_count": { "type": "integer", "description": "The number of emails in the thread.", "example": 2 }, "has_attachment": { "type": "boolean", "description": "Whether the most recent email in the thread has an attachment.", "example": true }, "has_draft": { "type": "boolean", "description": "Whether the thread has an unsent draft.", "example": false }, "read": { "type": "boolean", "description": "True only when every email in the thread is read.", "example": false }, "received_at": { "type": "string", "format": "date-time", "description": "Timestamp when the thread was last active.", "example": "2026-08-05T14:03:11.229Z" }, "folder": { "type": "string", "enum": [ "inbox", "archive", "spam", "sent", "trash" ], "description": "The folder the thread is in. Every thread is in exactly one folder. `inbox` holds threads with at least one received email. `archive` and `spam` hold threads moved there. `trash` holds threads scheduled for deletion in 30 days. `sent` holds threads whose emails are all outbound, and is assigned automatically.", "example": "inbox" } } }, "InboxThreadSearchResult": { "allOf": [ { "$ref": "#/components/schemas/InboxThread" }, { "type": "object", "required": [ "matched_email_id" ], "properties": { "matched_email_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the email in the thread that matched the search. When `query` has words or phrases, it is the most relevant match. Otherwise, it is the newest. It is the same `id` that the list thread emails endpoint returns, so use it as `email_id` with the get, reply and forward endpoints. Null when the search index returns no matched email for the thread.", "example": "e8a3f1c6-2b9d-4e5a-a7c4-9d1b6f3e2a80" } } } ] }, "InboxThreadSummary": { "type": "object", "description": "The summary of a single thread.", "required": [ "object", "id", "subject", "folder", "labels", "read" ], "properties": { "object": { "type": "string", "description": "The object type.", "example": "inbox_thread" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12" }, "subject": { "type": [ "string", "null" ], "description": "The subject of the thread.", "example": "Refund for order 1041" }, "folder": { "type": "string", "enum": [ "inbox", "archive", "spam", "sent", "trash" ], "description": "The folder the thread is in.", "example": "inbox" }, "labels": { "type": "array", "description": "The labels attached to the thread.", "items": { "$ref": "#/components/schemas/InboxThreadLabel" } }, "read": { "type": "boolean", "description": "True only when every email in the thread is read.", "example": false } } }, "ListInboxThreadsResponseSuccess": { "type": "object", "required": [ "object", "has_more", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": true }, "data": { "type": "array", "description": "The matching threads, most recently active first.", "items": { "$ref": "#/components/schemas/InboxThread" } } } }, "SearchInboxThreadsResponseSuccess": { "type": "object", "required": [ "object", "has_more", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": true }, "data": { "type": "array", "description": "The matching threads, most recently active first.", "items": { "$ref": "#/components/schemas/InboxThreadSearchResult" } } } }, "GetInboxThreadResponseSuccess": { "$ref": "#/components/schemas/InboxThreadSummary" }, "UpdateInboxThreadOptions": { "type": "object", "description": "At least one of `read` or `folder` is required. Use the thread labels endpoints to change labels.", "anyOf": [ { "required": [ "read" ] }, { "required": [ "folder" ] } ], "properties": { "read": { "type": "boolean", "description": "Marks every email in the thread read or unread.", "example": true }, "folder": { "type": "string", "enum": [ "inbox", "archive", "spam", "trash" ], "description": "Moves the thread to this folder. `sent` is assigned automatically and cannot be set.", "example": "archive" } } }, "UpdateInboxThreadResponseSuccess": { "$ref": "#/components/schemas/InboxThreadSummary" }, "AddInboxThreadLabelsOptions": { "type": "object", "required": [ "labels" ], "properties": { "labels": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the labels to apply to the thread. Between 1 and 10 IDs, each a label of the inbox.", "example": [ "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" ] } } }, "SetInboxThreadLabelsOptions": { "type": "object", "required": [ "labels" ], "properties": { "labels": { "type": "array", "maxItems": 100, "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the labels the thread carries after the change. Up to 100 IDs, each a label of the inbox. Pass an empty array to take every label off the thread.", "example": [ "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34" ] } } }, "InboxThreadLabelList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "Every label on the thread after the change.", "items": { "$ref": "#/components/schemas/InboxThreadLabel" } } } }, "AddInboxThreadLabelsResponseSuccess": { "$ref": "#/components/schemas/InboxThreadLabelList" }, "SetInboxThreadLabelsResponseSuccess": { "$ref": "#/components/schemas/InboxThreadLabelList" }, "RemoveInboxThreadLabelResponseSuccess": { "$ref": "#/components/schemas/InboxThreadLabelList" }, "RemoveInboxThreadResponseSuccess": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string", "description": "The object type.", "example": "inbox_thread" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12" }, "deleted": { "type": "boolean", "description": "True when this call moved the thread to `trash`. False when the thread was already there.", "example": true } } }, "InboxThreadEmailAttachment": { "type": "object", "required": [ "id", "filename", "size" ], "properties": { "id": { "type": "string", "description": "The ID of the attachment.", "example": "9d4f2b81-6c3a-4e7d-8b12-0a5c6d7e8f90" }, "filename": { "type": [ "string", "null" ], "description": "The filename of the attachment.", "example": "receipt.pdf" }, "size": { "type": [ "integer", "null" ], "description": "The size of the attachment in bytes.", "example": 20841 } } }, "InboxThreadEmail": { "type": "object", "required": [ "id", "direction", "from", "to", "cc", "bcc", "reply_to", "subject", "message_id", "html", "text", "attachments", "read", "received_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the message.", "example": "5b1a9f47-2c8d-4e6f-9a03-1d2e3f4a5b60" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Whether the inbox received the message (`inbound`) or sent it (`outbound`). A message the inbox sent to itself is `inbound`, so a reply to it goes to its sender.", "example": "inbound" }, "from": { "type": "string", "description": "Sender email address. Includes the display name when the sender has one, in the format \"Name \".", "example": "Ada Lovelace " }, "to": { "type": "array", "items": { "type": "string" }, "description": "The recipients of the message. For a received message, these are the addresses it was delivered to, not the full `To` header.", "example": [ "support@acme.com" ] }, "cc": { "type": "array", "items": { "type": "string" }, "description": "The CC recipients of the message.", "example": [] }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "The BCC recipients of the message. Always empty for a received message.", "example": [] }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "The Reply-To addresses of the message.", "example": [ "replies@example.org" ] }, "subject": { "type": [ "string", "null" ], "description": "The subject of the message.", "example": "Refund for order 1041" }, "message_id": { "type": [ "string", "null" ], "description": "The Message-ID header of the message.", "example": "<1041@example.org>" }, "html": { "type": [ "string", "null" ], "description": "The HTML body.", "example": "

Could I get a refund for order 1041?

" }, "text": { "type": [ "string", "null" ], "description": "The plain-text body.", "example": "Could I get a refund for order 1041?" }, "attachments": { "type": "array", "description": "The attachments of the message.", "items": { "$ref": "#/components/schemas/InboxThreadEmailAttachment" } }, "read": { "type": "boolean", "description": "Whether the message has been read.", "example": false }, "received_at": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox received the message, or when the inbox sent it.", "example": "2026-08-05T14:03:11.229Z" } } }, "ListInboxThreadEmailsResponseSuccess": { "type": "object", "required": [ "object", "has_more", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "The messages of the thread on this page, oldest first.", "items": { "$ref": "#/components/schemas/InboxThreadEmail" } } } }, "GetInboxThreadEmailResponseSuccess": { "$ref": "#/components/schemas/InboxThreadEmail" }, "ReplyInboxThreadEmailOptions": { "type": "object", "description": "At least one of `html` or `text` must contain more than whitespace.", "anyOf": [ { "required": [ "html" ] }, { "required": [ "text" ] } ], "properties": { "cc": { "description": "CC recipient email address. For multiple addresses, send as an array of strings. Without `reply_all`, the reply copies only these addresses. With `reply_all`, these addresses are merged with the copied recipients, without duplicates. `cc` and `bcc` combined must be fewer than 50 addresses. After the `to` recipients are added, the reply cannot exceed 50 recipients. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 49 }, { "type": "null" } ], "example": [ "billing@acme.com" ] }, "bcc": { "description": "BCC recipient email address. For multiple addresses, send as an array of strings. BCC recipients of the original message are never copied. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 49 }, { "type": "null" } ], "example": [ "records@acme.com" ] }, "html": { "type": "string", "description": "The HTML body of the reply.", "example": "

Refund issued for order 1041.

" }, "text": { "type": "string", "description": "The plain-text body of the reply.", "example": "Refund issued for order 1041." }, "subject": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The subject of the reply. Cannot be only whitespace or contain a line break. When omitted, the thread subject is used, prefixed with `Re:` if it does not already start with it.", "example": "Re: Refund for order 1041" }, "reply_all": { "type": "boolean", "default": false, "description": "Reply to everyone on the original message. For a message the inbox received, the reply goes to its `Reply-To` addresses, or to its sender when it has none, and copies the other addresses of its `To` header and its `cc` recipients in `cc`. For a message the inbox sent, the reply goes to that message's `Reply-To` addresses when they are not the inbox address, otherwise to its `to` recipients, and copies its `cc` recipients. The inbox address is always excluded, and duplicates are removed.", "example": false }, "attachments": { "type": [ "array", "null" ], "description": "Files to attach, as on `POST /emails`. Each one needs `content` or `path`. The `content` of all files can total at most 25 MB. A `path` file does not count toward the 25 MB, because it is fetched when the email is sent. An empty file, a blocked file type, a `path` that does not start with `http` or that starts with `http://localhost:`, or a `content_type` that is not a valid MIME type returns a 422. Other `path` problems fail the email when it is sent, not the request.", "items": { "$ref": "#/components/schemas/Attachment" } }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom headers to add to the email. The `In-Reply-To`, `References` and `Reply-To` headers are set by Resend and cannot be set here. Sending one of them, in any letter case, returns a 422. Header names cannot be empty, and names and values cannot contain line breaks or null characters, or the request returns a 422. `null` means no custom headers.", "example": { "X-Ticket-Id": "4821" } } } }, "ReplyInboxThreadEmailResponseSuccess": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the sent email. Use it with the emails endpoints.", "example": "6a0c8e58-3d9e-4f7a-8b14-2e3f4a5b6c71" } } }, "ForwardInboxThreadEmailOptions": { "type": "object", "required": [ "to" ], "properties": { "to": { "description": "Recipient email address. For multiple addresses, send as an array of strings. Must name at least one address. `to`, `cc` and `bcc` combined cannot exceed 50 recipients. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 } ], "example": [ "colleague@example.org" ] }, "cc": { "description": "CC recipient email address. For multiple addresses, send as an array of strings. Counts toward the 50-recipient limit. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ], "example": [ "billing@acme.com" ] }, "bcc": { "description": "BCC recipient email address. For multiple addresses, send as an array of strings. Counts toward the 50-recipient limit. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ], "example": [ "records@acme.com" ] }, "html": { "type": "string", "description": "An HTML note sent above the quoted original.", "example": "

Flagging this refund request for you.

" }, "text": { "type": "string", "description": "A plain-text note sent above the quoted original.", "example": "Flagging this refund request for you." }, "subject": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The subject of the forward. Cannot be only whitespace or contain a line break. When omitted, the thread subject is used, prefixed with `Fwd:` if it does not already start with it.", "example": "Fwd: Refund for order 1041" }, "attachments": { "type": [ "array", "null" ], "description": "Files to attach, as on `POST /emails`. Each one needs `content` or `path`. They share one limit with the attachments of the original message, which the forward also sends. Together they can have at most 25 MB of `content`. A `path` file does not count toward the 25 MB, because it is fetched when the email is sent. An empty file, a blocked file type, a `path` that does not start with `http` or that starts with `http://localhost:`, or a `content_type` that is not a valid MIME type returns a 422. Other `path` problems fail the email when it is sent, not the request.", "items": { "$ref": "#/components/schemas/Attachment" } }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom headers to add to the email. The `In-Reply-To`, `References` and `Reply-To` headers are set by Resend and cannot be set here. Sending one of them, in any letter case, returns a 422. Header names cannot be empty, and names and values cannot contain line breaks or null characters, or the request returns a 422. `null` means no custom headers.", "example": { "X-Ticket-Id": "4821" } } } }, "ForwardInboxThreadEmailResponseSuccess": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the sent email. Use it with the emails endpoints.", "example": "6a0c8e58-3d9e-4f7a-8b14-2e3f4a5b6c71" } } }, "InboxDraftAttachmentInput": { "type": "object", "description": "A file to store on a draft. Unlike `POST /emails` attachments, a draft attachment cannot use `path` or `content_id`. A `path` without `content` returns a 422, and when both are sent, `path` is ignored.", "required": [ "content", "filename", "content_type" ], "properties": { "content": { "type": "string", "description": "The content of the file, encoded in base64. It cannot be empty.", "example": "aGVsbG8gZTJl" }, "filename": { "type": "string", "minLength": 1, "description": "The filename of the attachment. A blocked file type returns a 422.", "example": "receipt.pdf" }, "content_type": { "type": "string", "minLength": 1, "description": "The MIME type of the attachment. It must be a valid MIME type, such as `application/pdf`, or the request returns a 422.", "example": "application/pdf" } } }, "InboxDraftAttachment": { "type": "object", "description": "A file stored on a draft.", "required": [ "id", "filename", "content_type", "size" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment.", "example": "5c1e9d2a-7b3f-4e8a-9c6d-2f0a1b3c4d5e" }, "filename": { "type": "string", "description": "The filename of the attachment.", "example": "receipt.pdf" }, "content_type": { "type": "string", "description": "The MIME type of the attachment.", "example": "application/pdf" }, "size": { "type": "integer", "description": "The size of the attachment in bytes.", "example": 20841 } } }, "InboxDraft": { "type": "object", "required": [ "object", "id", "type", "to", "cc", "bcc", "subject", "html", "text", "thread_id", "reply_to_email_id", "email_id", "created_at", "updated_at", "attachments" ], "properties": { "object": { "type": "string", "description": "The object type.", "example": "inbox_draft" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32" }, "type": { "type": "string", "enum": [ "standalone", "reply" ], "description": "`reply` when the draft replies to an email in an existing thread. `standalone` when the draft starts a new thread.", "example": "standalone" }, "to": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The recipients. `null` or empty when no recipients are set.", "example": [ "ada@example.org" ] }, "cc": { "type": "array", "items": { "type": "string" }, "description": "The CC recipients.", "example": [] }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "The BCC recipients.", "example": [] }, "subject": { "type": [ "string", "null" ], "description": "The subject.", "example": "Refund for order 1041" }, "html": { "type": [ "string", "null" ], "description": "The HTML body.", "example": "

Refund issued for order 1041.

" }, "text": { "type": [ "string", "null" ], "description": "The plain text body. A reply draft created without a body has an empty string.", "example": "Refund issued for order 1041." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The Thread ID when the draft is a reply. `null` otherwise.", "example": null }, "reply_to_email_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The Email ID the draft replies to. `null` otherwise.", "example": null }, "email_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the outbound email queued when the draft was sent. `null` until the draft is sent.", "example": null }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created.", "example": "2026-08-05T14:12:04.110Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last saved.", "example": "2026-08-05T14:12:04.110Z" }, "attachments": { "type": "array", "description": "The files stored on the draft.", "items": { "$ref": "#/components/schemas/InboxDraftAttachment" } } } }, "InboxDraftListItem": { "type": "object", "required": [ "id", "type", "to", "cc", "bcc", "subject", "snippet", "thread_id", "reply_to_email_id", "updated_at", "attachments" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32" }, "type": { "type": "string", "enum": [ "standalone", "reply" ], "description": "`reply` when the draft replies to an email in an existing thread. `standalone` when the draft starts a new thread.", "example": "standalone" }, "to": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The recipients. `null` or empty when no recipients are set.", "example": [ "ada@example.org" ] }, "cc": { "type": "array", "items": { "type": "string" }, "description": "The CC recipients.", "example": [] }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "The BCC recipients.", "example": [] }, "subject": { "type": [ "string", "null" ], "description": "The subject.", "example": "Refund for order 1041" }, "snippet": { "type": [ "string", "null" ], "description": "A short preview of the body.", "example": "Refund issued for order 1041." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The Thread ID when the draft is a reply. `null` otherwise.", "example": null }, "reply_to_email_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The Email ID the draft replies to. `null` otherwise.", "example": null }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last saved.", "example": "2026-08-05T14:12:04.110Z" }, "attachments": { "type": "array", "description": "The files stored on the draft.", "items": { "$ref": "#/components/schemas/InboxDraftAttachment" } } } }, "ListInboxDraftsResponseSuccess": { "type": "object", "required": [ "object", "has_more", "data" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "The unsent drafts on this page, most recently updated first.", "items": { "$ref": "#/components/schemas/InboxDraftListItem" } } } }, "CreateInboxDraftOptions": { "type": "object", "description": "At least one of `to`, `cc`, `bcc`, `subject`, `text`, `html` or `attachments` must be non-empty. The combined recipients of `to`, `cc` and `bcc` cannot exceed 50. `thread_id` and `reply_to_email_id` must be sent together or not at all.", "properties": { "to": { "description": "The recipients. For multiple addresses, send an array of strings. Each value can include a friendly name, for example `Ada Lovelace `. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ], "example": [ "ada@example.org" ] }, "cc": { "description": "The CC recipients. For multiple addresses, send an array of strings. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ] }, "bcc": { "description": "The BCC recipients. For multiple addresses, send an array of strings. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ] }, "subject": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000, "description": "The subject. Max 2000 characters. A string that is only whitespace, or that contains a line break, is rejected.", "example": "Refund for order 1041" }, "html": { "type": [ "string", "null" ], "description": "The HTML body.", "example": "

Refund issued for order 1041.

" }, "text": { "type": [ "string", "null" ], "description": "The plain text body.", "example": "Refund issued for order 1041." }, "attachments": { "type": [ "array", "null" ], "description": "Files to store on the draft. Each one needs `content`, `filename` and `content_type`. A `path` without `content` returns a 422, and when both are sent, `path` is ignored. A `content_id` returns a 422. The files on a draft can total at most 25 MB. An empty file or a blocked file type returns a 422.", "items": { "$ref": "#/components/schemas/InboxDraftAttachmentInput" } }, "thread_id": { "type": "string", "format": "uuid", "description": "The Thread ID to reply in. Must be sent with `reply_to_email_id`.", "example": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12" }, "reply_to_email_id": { "type": "string", "format": "uuid", "description": "The Email ID to reply to, as returned in `data[].id` by the list thread emails endpoint. Must be sent with `thread_id`.", "example": "5b1a9f47-2c8d-4e6f-9a03-1d2e3f4a5b60" } } }, "CreateInboxDraftResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "inbox_draft" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32" } } }, "GetInboxDraftResponseSuccess": { "$ref": "#/components/schemas/InboxDraft" }, "UpdateInboxDraftOptions": { "type": "object", "description": "Send at least one of `to`, `cc`, `bcc`, `subject`, `text`, `html` or `attachments`. Omitted fields are left unchanged. Setting `text` or `html` replaces the whole body, so the body part you omit becomes `null`. The merged draft must contain at least one non-empty field, and its combined recipients cannot exceed 50.", "anyOf": [ { "required": [ "to" ] }, { "required": [ "cc" ] }, { "required": [ "bcc" ] }, { "required": [ "subject" ] }, { "required": [ "text" ] }, { "required": [ "html" ] }, { "required": [ "attachments" ] } ], "properties": { "to": { "description": "The recipients. For multiple addresses, send an array of strings. Each value can include a friendly name. Pass `null` to clear. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ], "example": [ "ada@example.org" ] }, "cc": { "description": "The CC recipients. Pass `null` or `[]` to clear. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ] }, "bcc": { "description": "The BCC recipients. Pass `null` or `[]` to clear. Each address is `email@example.com` or `Name `. An address that is not valid returns a 422.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, { "type": "null" } ] }, "subject": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000, "description": "The subject. Max 2000 characters. Cannot be only whitespace or contain a line break. Pass `null` to clear.", "example": "Refund issued for order 1041" }, "html": { "type": [ "string", "null" ], "description": "The HTML body. Pass `null` to clear." }, "text": { "type": [ "string", "null" ], "description": "The plain text body. Pass `null` to clear." }, "attachments": { "type": [ "array", "null" ], "description": "Files to store on the draft. Each one needs `content`, `filename` and `content_type`. A `path` without `content` returns a 422, and when both are sent, `path` is ignored. A `content_id` returns a 422. The files on a draft can total at most 25 MB. An empty file or a blocked file type returns a 422. Sending the field replaces every attachment on the draft. Send `[]` to remove them all. `null` also removes them all.", "items": { "$ref": "#/components/schemas/InboxDraftAttachmentInput" } } } }, "UpdateInboxDraftResponseSuccess": { "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "description": "The object type. Always `inbox_draft`.", "example": "inbox_draft" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32" } } }, "RemoveInboxDraftResponseSuccess": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string", "description": "The object type.", "example": "inbox_draft" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates whether the draft was successfully deleted.", "example": true } } }, "SendInboxDraftOptions": { "type": "object", "properties": { "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom headers to add to the email. The `In-Reply-To`, `References` and `Reply-To` headers are set by Resend and cannot be set here. Sending one of them, in any letter case, returns a 422. Header names cannot be empty, and names and values cannot contain line breaks or null characters, or the request returns a 422. `null` means no custom headers.", "example": { "X-Ticket-Id": "4821" } } } }, "SendInboxDraftResponseSuccess": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the sent email. Use it with the emails endpoints.", "example": "6a0c8e58-3d9e-4f7a-8b14-2e3f4a5b6c71" } } }, "InboxEventSource": { "type": "string", "enum": [ "api", "dashboard", "agent", "system" ], "description": "What made the change.", "example": "dashboard" }, "InboxEventEmailAttachment": { "type": "object", "description": "An attachment on an email in an inbox webhook event.", "required": [ "id", "filename", "size" ], "properties": { "id": { "type": "string", "description": "The ID of the attachment.", "example": "2a0c9ce0-3112-4728-976e-47ddcd16a318" }, "filename": { "type": [ "string", "null" ], "description": "The filename of the attachment.", "example": "invoice.pdf" }, "size": { "type": [ "integer", "null" ], "description": "The size of the attachment in bytes.", "example": 48213 } } }, "InboxEventEmail": { "type": "object", "description": "The email carried by an inbox webhook event. It has no `html` or `text`.", "required": [ "id", "direction", "from", "to", "cc", "bcc", "reply_to", "subject", "message_id", "attachments", "read", "received_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the email.", "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Whether the email was received by the inbox or sent from it.", "example": "inbound" }, "from": { "type": "string", "description": "The sender, as an address or as `Name
`.", "example": "Steve Wozniak " }, "to": { "type": "array", "items": { "type": "string" }, "description": "The recipients of the email.", "example": [ "support@acme.com" ] }, "cc": { "type": "array", "items": { "type": "string" }, "description": "The CC recipients of the email." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "The BCC recipients of the email." }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "The Reply-To addresses." }, "subject": { "type": [ "string", "null" ], "description": "The subject of the email.", "example": "Question about my invoice" }, "message_id": { "type": [ "string", "null" ], "description": "The Message-ID header of the email.", "example": "" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/InboxEventEmailAttachment" }, "description": "The attachments on the email." }, "read": { "type": "boolean", "description": "Whether the email has been read.", "example": false }, "received_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email arrived or was sent.", "example": "2026-09-29T12:00:00.000Z" } } }, "InboxEventDraft": { "type": "object", "description": "The draft carried by an inbox webhook event. It has no `html` or `text`.", "required": [ "object", "id", "type", "to", "cc", "bcc", "subject", "thread_id", "reply_to_email_id", "email_id", "created_at", "updated_at", "attachments" ], "properties": { "object": { "type": "string", "description": "The object type. Always `inbox_draft`.", "example": "inbox_draft" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "9a2b7c4d-1e3f-4a5b-8c6d-0e1f2a3b4c5d" }, "type": { "type": "string", "enum": [ "standalone", "reply" ], "description": "`standalone` for a new conversation, or `reply`.", "example": "reply" }, "to": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The recipients.", "example": [ "steve@acme.com" ] }, "cc": { "type": "array", "items": { "type": "string" }, "description": "The CC recipients." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "The BCC recipients." }, "subject": { "type": [ "string", "null" ], "description": "The subject.", "example": "Re: Question about my invoice" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the thread when this draft is a reply. Null otherwise.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "reply_to_email_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the email this draft replies to. Null otherwise.", "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }, "email_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the queued outbound email after send. Null until then.", "example": null }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created.", "example": "2026-09-29T11:58:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last saved.", "example": "2026-09-29T12:00:00.000Z" }, "attachments": { "type": "array", "description": "The files stored on the draft.", "items": { "$ref": "#/components/schemas/InboxDraftAttachment" } } } }, "InboxEventData": { "type": "object", "description": "The data of an `inbox.created` or `inbox.updated` event.", "required": [ "source", "inbox_id" ], "properties": { "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "inbox": { "$ref": "#/components/schemas/Inbox", "description": "The inbox as it is when the webhook is sent. Absent when the inbox no longer exists." } } }, "InboxDeletedEventData": { "type": "object", "description": "The data of an `inbox.deleted` event.", "required": [ "source", "inbox_id" ], "properties": { "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" } } }, "InboxThreadEmailEventData": { "type": "object", "description": "The data of an `inbox.thread.created`, `inbox.email.received` or `inbox.email.sent` event.", "required": [ "source", "inbox_id", "thread_id", "email_id" ], "properties": { "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "email_id": { "type": "string", "format": "uuid", "description": "The ID of the email.", "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists." }, "email": { "$ref": "#/components/schemas/InboxEventEmail", "description": "The email as it is when the webhook is sent, without `html` or `text`. Fetch the body with Retrieve Thread Email. Absent when the email no longer exists." } } }, "InboxThreadFolderUpdatedEventData": { "type": "object", "description": "The data of an `inbox.thread.folder.updated` event.", "required": [ "from", "to", "source", "inbox_id", "thread_id" ], "properties": { "from": { "type": "string", "enum": [ "inbox", "archive", "spam", "trash" ], "description": "The folder the thread was in.", "example": "inbox" }, "to": { "type": "string", "enum": [ "inbox", "archive", "spam", "trash" ], "description": "The folder the thread moved to.", "example": "archive" }, "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists." } } }, "InboxThreadAssignedEventData": { "type": "object", "description": "The data of an `inbox.thread.assigned` event.", "required": [ "assignee_email", "assigned_by_email", "previous_assignee_email", "source", "inbox_id", "thread_id" ], "properties": { "assignee_email": { "type": [ "string", "null" ], "description": "The email of the member the thread is now assigned to.", "example": "ada@acme.com" }, "assigned_by_email": { "type": [ "string", "null" ], "description": "The email of the member who made the assignment. Null when no member made it.", "example": "grace@acme.com" }, "previous_assignee_email": { "type": [ "string", "null" ], "description": "The email of the member the thread was assigned to before. Null when it was unassigned.", "example": null }, "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists." } } }, "InboxThreadUnassignedEventData": { "type": "object", "description": "The data of an `inbox.thread.unassigned` event.", "required": [ "previous_assignee_email", "source", "inbox_id", "thread_id" ], "properties": { "previous_assignee_email": { "type": [ "string", "null" ], "description": "The email of the member the thread was assigned to.", "example": "ada@acme.com" }, "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists." } } }, "InboxThreadLabelsUpdatedEventData": { "type": "object", "description": "The data of an `inbox.thread.labels.updated` event. Adding labels fills only `added`. Removing one label fills only `removed`. Setting the labels of a thread can fill both.", "required": [ "added", "removed", "source", "inbox_id", "thread_id" ], "properties": { "added": { "type": "array", "items": { "$ref": "#/components/schemas/InboxThreadLabel" }, "description": "The labels applied to the thread." }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/InboxThreadLabel" }, "description": "The labels removed from the thread." }, "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists." } } }, "InboxDraftEventData": { "type": "object", "description": "The data of an `inbox.draft.created`, `inbox.draft.updated` or `inbox.draft.deleted` event.", "required": [ "source", "inbox_id", "draft_id" ], "properties": { "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread. Only on reply drafts.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "draft_id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "9a2b7c4d-1e3f-4a5b-8c6d-0e1f2a3b4c5d" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists. Only on reply drafts." }, "draft": { "$ref": "#/components/schemas/InboxEventDraft", "description": "The draft as it is when the webhook is sent, without `html` or `text`. Fetch the body with Retrieve Draft. Absent when the draft no longer exists." } } }, "InboxDraftSentEventData": { "type": "object", "description": "The data of an `inbox.draft.sent` event.", "required": [ "source", "inbox_id", "thread_id", "email_id", "draft_id" ], "properties": { "source": { "$ref": "#/components/schemas/InboxEventSource" }, "inbox_id": { "type": "string", "format": "uuid", "description": "The ID of the inbox.", "example": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1" }, "thread_id": { "type": "string", "format": "uuid", "description": "The ID of the thread.", "example": "7c1f0a2e-5d3b-4e8a-9f61-2b8d4c6e1a90" }, "email_id": { "type": "string", "format": "uuid", "description": "The ID of the email.", "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }, "draft_id": { "type": "string", "format": "uuid", "description": "The ID of the draft.", "example": "9a2b7c4d-1e3f-4a5b-8c6d-0e1f2a3b4c5d" }, "thread": { "$ref": "#/components/schemas/InboxThreadSummary", "description": "The thread as it is when the webhook is sent. Absent when the thread no longer exists." }, "email": { "$ref": "#/components/schemas/InboxEventEmail", "description": "The email as it is when the webhook is sent, without `html` or `text`. Fetch the body with Retrieve Thread Email. Only when the email is already on the thread when the webhook is sent." }, "draft": { "$ref": "#/components/schemas/InboxEventDraft", "description": "The draft as it is when the webhook is sent, without `html` or `text`. Fetch the body with Retrieve Draft. Absent when the draft no longer exists." } } }, "InboxCreatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.created", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxEventData" } } }, "InboxUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxEventData" } } }, "InboxDeletedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.deleted", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxDeletedEventData" } } }, "InboxThreadCreatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.thread.created", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadEmailEventData" } } }, "InboxEmailReceivedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.email.received", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadEmailEventData" } } }, "InboxEmailSentEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.email.sent", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadEmailEventData" } } }, "InboxThreadFolderUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.thread.folder.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadFolderUpdatedEventData" } } }, "InboxThreadAssignedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.thread.assigned", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadAssignedEventData" } } }, "InboxThreadUnassignedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.thread.unassigned", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadUnassignedEventData" } } }, "InboxThreadLabelsUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.thread.labels.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxThreadLabelsUpdatedEventData" } } }, "InboxDraftCreatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.draft.created", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxDraftEventData" } } }, "InboxDraftUpdatedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.draft.updated", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxDraftEventData" } } }, "InboxDraftSentEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.draft.sent", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxDraftSentEventData" } } }, "InboxDraftDeletedEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "const": "inbox.draft.deleted", "description": "The event type." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was emitted.", "example": "2026-09-29T12:00:00.000Z" }, "data": { "$ref": "#/components/schemas/InboxDraftEventData" } } } } } }