diff --git a/resend.json b/resend.json index a9aa54a..c46b551 100644 --- a/resend.json +++ b/resend.json @@ -44,6 +44,10 @@ "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." @@ -1249,6 +1253,112 @@ } } }, + "/contacts/imports": { + "post": { + "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": { + "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": { + "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": { "tags": [ @@ -2893,666 +3003,1773 @@ } } }, - "components": { - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" + "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." + } + } } }, - "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" + "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" + } + } + } }, - "description": "Return items after this cursor." - }, - "PaginationBefore": { - "in": "query", - "name": "before", - "required": false, - "schema": { - "type": "string" + "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" + } + } + } }, - "description": "Return items before this cursor." + "responses": { + "2XX": { + "description": "Return any 2xx status code to acknowledge receipt of the event." + } + } } }, - "schemas": { - "SendEmailRequest": { - "type": "object", - "required": [ - "from", - "to", - "subject" + "email.bounced": { + "post": { + "summary": "Email bounced", + "description": "Occurs whenever the recipient's mail server permanently rejected the email.", + "tags": [ + "Webhook Events" ], - "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 + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailBouncedEvent" } - ] - }, - "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" - } + } + } + }, + "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" } - ] - }, - "cc": { - "description": "Cc recipient email address. For multiple addresses, send as an array of strings.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "string" - } + } + } + }, + "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." + } + } + } + }, + "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." + } + } + } + } + }, + "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." + } + }, + "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 } ] }, - "reply_to": { - "description": "Reply-to email address. For multiple addresses, send as an array of strings.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] + "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." + } + } + }, + "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" + }, + "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", + "format": "date-time", + "description": "The date and time the email was created.", + "example": "2023-04-03T22:13:42.674981+00: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" + } + } + } + }, + "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", + "format": "date-time", + "description": "The date and time the domain was created." + }, + "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", + "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." }, - "html": { + "status": { "type": "string", - "description": "The HTML version of the message." + "enum": [ + "pending", + "verified", + "failed", + "temporary_failure", + "not_started" + ], + "description": "The status of the record." }, - "text": { + "value": { "type": "string", - "description": "The plain text version of the message." + "description": "The value of the record." }, - "template": { - "allOf": [ - { - "$ref": "#/components/schemas/EmailTemplateInput" - }, - { - "description": "Use a published template to send the email. If provided, do not include html or text." - } - ] + "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" }, - "headers": { - "type": "object", - "description": "Custom headers to add to the email." + "id": { + "type": "string", + "description": "The ID of the domain.", + "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, - "scheduled_at": { + "name": { "type": "string", - "description": "Schedule email to be sent later. The date should be in ISO 8601 format." + "description": "The name of the domain.", + "example": "example.com" }, - "attachments": { + "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", + "format": "date-time", + "description": "The date and time the domain was created.", + "example": "2023-04-26T20:21:26.347412+00: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/Attachment" + "$ref": "#/components/schemas/DomainRecord" } + } + } + }, + "VerifyDomainResponse": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "The type of object.", + "example": "domain" }, - "tags": { + "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/Tag" + "$ref": "#/components/schemas/ListDomainsItem" } + } + } + }, + "ListDomainsItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the domain.", + "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, - "topic_id": { + "name": { "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." + "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", + "format": "date-time", + "description": "The date and time the domain was created.", + "example": "2023-04-26T20:21:26.347412+00:00" + }, + "region": { + "type": "string", + "description": "The region where the domain is hosted.", + "example": "us-east-1" + }, + "capabilities": { + "$ref": "#/components/schemas/DomainCapabilities" } } }, - "Attachment": { + "UpdateDomainResponseSuccess": { "type": "object", "properties": { - "content": { + "id": { "type": "string", - "format": "binary", - "description": "Content of an attached file." + "description": "The ID of the updated domain.", + "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, - "filename": { + "object": { "type": "string", - "description": "Name of attached file." + "description": "The object type representing the updated domain.", + "example": "domain" + } + } + }, + "DeleteDomainResponse": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "The type of object.", + "example": "domain" }, - "path": { + "id": { "type": "string", - "description": "Path where the attachment file is hosted" + "description": "The ID of the domain.", + "example": "d91cd9bd-1176-453e-8fc1-35364d380206" }, - "content_type": { + "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": "Optional content type for the attachment, if not set it will be derived from the filename property" + "description": "The ID of the API key." }, - "content_id": { + "token": { "type": "string", - "description": "Content ID for embedding inline images using cid references (e.g., cid:image001)." + "description": "The token of the API key." } } }, - "Tag": { + "ListApiKeysResponse": { "type": "object", "properties": { - "name": { + "object": { "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." + "description": "Type of the response object.", + "example": "list" }, - "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." + "has_more": { + "type": "boolean", + "description": "Indicates if there are more results available.", + "example": false + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApiKey" + } } } }, - "EmailTemplateInput": { + "ApiKey": { "type": "object", "properties": { "id": { "type": "string", - "description": "The id of the published email template." + "description": "The ID of the API key." }, - "variables": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ] - }, - "description": "Template variables object with key/value pairs.", - "example": { - "variableName": "Sign up now", - "variableName2": 123 - } + "name": { + "type": "string", + "description": "The name of the API key." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "The date and time the API key was created." + }, + "last_used_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "The date and time the API key was last used." } - }, - "required": [ - "id" - ] + } }, - "SendEmailResponse": { + "DeleteApiKeyResponse": { "type": "object", "properties": { + "object": { + "type": "string", + "description": "The type of object.", + "example": "api_key" + }, "id": { "type": "string", - "description": "The ID of the sent email." + "description": "The ID of the API key." + }, + "deleted": { + "type": "boolean", + "description": "Indicates whether the API key was successfully deleted.", + "example": true } } }, - "UpdateEmailOptions": { + "CreateAudienceOptions": { "type": "object", + "deprecated": true, + "required": [ + "name" + ], "properties": { - "scheduled_at": { + "name": { "type": "string", - "description": "Schedule email to be sent later. The date should be in ISO 8601 format." + "description": "The name of the audience you want to create." } } }, - "Email": { + "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 type of object.", - "example": "email" + "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 email.", - "example": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" + "description": "The ID of the audience.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "to": { - "type": "array", - "items": { - "type": "string", - "description": "The email addresses of the recipients." - }, - "example": [ - "delivered@resend.dev" - ] + "object": { + "type": "string", + "description": "The object of the audience.", + "example": "audience" }, - "from": { + "name": { "type": "string", - "description": "The email address of the sender.", - "example": "Acme " + "description": "The name of the audience.", + "example": "Registered Users" }, "created_at": { "type": "string", - "format": "date-time", - "description": "The date and time the email was created.", - "example": "2023-04-03T22:13:42.674981+00:00" - }, - "subject": { + "description": "The date that the object was created.", + "example": "2023-10-06T22:59:55.977Z" + } + } + }, + "RemoveAudienceResponseSuccess": { + "type": "object", + "deprecated": true, + "properties": { + "id": { "type": "string", - "description": "The subject line of the email.", - "example": "Hello World" + "description": "The ID of the audience.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "html": { + "object": { "type": "string", - "description": "The HTML body of the email.", - "example": "Congrats on sending your first email!" + "description": "The object of the audience.", + "example": "audience" }, - "text": { + "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": "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." + "description": "Type of the response object.", + "example": "list" }, - "reply_to": { + "data": { "type": "array", + "description": "Array containing audience information.", "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" + "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", + "format": "date-time", + "description": "Timestamp indicating when the audience was created.", + "example": "2023-10-06T22:59:55.977Z" + } + } + } } } }, - "ListEmailsResponse": { + "CreateContactOptions": { "type": "object", + "required": [ + "email" + ], "properties": { - "object": { + "email": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "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" }, - "has_more": { + "unsubscribed": { "type": "boolean", - "description": "Indicates if there are more results available.", + "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", "example": false }, - "data": { + "properties": { + "type": "object", + "additionalProperties": true, + "description": "A map of custom property keys and values to create." + }, + "segments": { "type": "array", - "description": "Array containing email information.", "items": { - "$ref": "#/components/schemas/Email" - } - } - } - }, - "CreateBatchEmailsResponse": { - "type": "object", - "properties": { - "data": { + "type": "string" + }, + "description": "Array of segment IDs to add the contact to." + }, + "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "The ID of the sent email." + "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 } } }, - "DomainCapabilities": { + "CreateContactResponseSuccess": { "type": "object", - "description": "Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.", "properties": { - "sending": { + "object": { "type": "string", - "enum": [ - "enabled", - "disabled" - ], - "description": "Enable or disable sending emails from this domain." + "description": "Type of the response object.", + "example": "contact" }, - "receiving": { + "id": { "type": "string", - "enum": [ - "enabled", - "disabled" - ], - "description": "Enable or disable receiving emails to this domain." + "description": "Unique identifier for the created contact.", + "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, - "CreateDomainRequest": { + "GetContactResponseSuccess": { "type": "object", - "required": [ - "name" - ], "properties": { - "name": { + "object": { "type": "string", - "description": "The name of the domain you want to create." + "description": "Type of the response object.", + "example": "contact" }, - "region": { + "id": { "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" + "description": "Unique identifier for the contact.", + "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, - "custom_return_path": { + "email": { "type": "string", - "description": "For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld)." + "description": "Email address of the contact.", + "example": "steve.wozniak@gmail.com" }, - "open_tracking": { - "type": "boolean", - "description": "Track the open rate of each email." + "first_name": { + "type": "string", + "description": "First name of the contact.", + "example": "Steve" }, - "click_tracking": { - "type": "boolean", - "description": "Track clicks within the body of each HTML email." + "last_name": { + "type": "string", + "description": "Last name of the contact.", + "example": "Wozniak" }, - "tls": { + "created_at": { "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." + "format": "date-time", + "description": "Timestamp indicating when the contact was created.", + "example": "2023-10-06T23:47:56.678Z" }, - "capabilities": { - "$ref": "#/components/schemas/DomainCapabilities" + "unsubscribed": { + "type": "boolean", + "description": "Indicates if the contact is unsubscribed.", + "example": false }, - "tracking_subdomain": { - "type": "string", - "description": "The subdomain to use for click and open tracking." + "properties": { + "type": "object", + "additionalProperties": true, + "description": "A map of custom property keys and values." } } }, - "CreateDomainResponse": { + "UpdateContactOptions": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "The ID of the domain." - }, - "name": { + "email": { "type": "string", - "description": "The name of the domain." + "description": "Email address of the contact.", + "example": "steve.wozniak@gmail.com" }, - "created_at": { + "first_name": { "type": "string", - "format": "date-time", - "description": "The date and time the domain was created." + "description": "First name of the contact.", + "example": "Steve" }, - "status": { + "last_name": { "type": "string", - "enum": [ - "pending", - "verified", - "failed", - "not_started", - "partially_verified", - "partially_failed" - ], - "description": "The status of the domain." + "description": "Last name of the contact.", + "example": "Wozniak" }, - "capabilities": { - "$ref": "#/components/schemas/DomainCapabilities" + "unsubscribed": { + "type": "boolean", + "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", + "example": false }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DomainRecord" - } + "properties": { + "type": "object", + "additionalProperties": true, + "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" }, - "region": { + "id": { "type": "string", - "description": "The region where the domain is hosted." + "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" }, - "open_tracking": { - "type": "boolean", - "description": "Whether open tracking is enabled for this domain." + "id": { + "type": "string", + "description": "Unique identifier for the removed contact.", + "example": "520784e2-887d-4c25-b53c-4ad46ad38100" }, - "click_tracking": { + "deleted": { "type": "boolean", - "description": "Whether click tracking is enabled for this domain." - }, - "tracking_subdomain": { + "description": "Indicates whether the contact was successfully deleted.", + "example": true + } + } + }, + "ListContactsResponseSuccess": { + "type": "object", + "properties": { + "object": { "type": "string", - "description": "The subdomain used for click and open tracking." + "description": "Type of the response object.", + "example": "list" + }, + "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", + "description": "First name of the contact.", + "example": "Steve" + }, + "last_name": { + "type": "string", + "description": "Last name of the contact.", + "example": "Wozniak" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the contact was created.", + "example": "2023-10-06T23:47:56.678Z" + }, + "unsubscribed": { + "type": "boolean", + "description": "Indicates if the contact is unsubscribed.", + "example": false + } + } + } } } }, - "UpdateDomainOptions": { + "CreateContactImportOptions": { "type": "object", + "required": [ + "file" + ], "properties": { - "open_tracking": { - "type": "boolean", - "description": "Track the open rate of each email." + "file": { + "type": "string", + "format": "binary", + "description": "CSV file to import. Maximum size is 50MB." }, - "click_tracking": { - "type": "boolean", - "description": "Track clicks within the body of each HTML email." + "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\"}}}" }, - "tls": { + "on_conflict": { "type": "string", - "description": "enforced | opportunistic.", - "default": "opportunistic" + "enum": [ + "upsert", + "skip" + ], + "default": "skip", + "description": "Strategy to use when an imported contact already exists.", + "example": "skip" }, - "capabilities": { - "$ref": "#/components/schemas/DomainCapabilities" + "segments": { + "type": "string", + "description": "JSON-encoded array of segments to add imported contacts to.", + "example": "[{\"id\":\"78261eea-8f8b-4381-83c6-79fa7120f1cf\"}]" }, - "tracking_subdomain": { + "topics": { "type": "string", - "description": "The subdomain to use for click and open tracking." + "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\"}]" } } }, - "DomainRecord": { + "CreateContactImportResponseSuccess": { "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": { + "object": { "type": "string", - "description": "The name of the DNS record." + "description": "Type of the response object.", + "example": "contact_import" }, - "type": { + "id": { "type": "string", - "enum": [ - "MX", - "TXT", - "CNAME", - "CAA" - ], - "description": "The DNS record type." + "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 }, - "ttl": { - "type": "string", - "description": "The time to live for the record." + "created": { + "type": "integer", + "description": "Number of contacts created by the import.", + "example": 80 }, - "status": { - "type": "string", - "enum": [ - "pending", - "verified", - "failed", - "temporary_failure", - "not_started" - ], - "description": "The status of the record." + "updated": { + "type": "integer", + "description": "Number of contacts updated by the import.", + "example": 10 }, - "value": { - "type": "string", - "description": "The value of the record." + "skipped": { + "type": "integer", + "description": "Number of rows skipped by the import.", + "example": 5 }, - "priority": { + "failed": { "type": "integer", - "description": "The priority of the record (only applicable for MX records)." + "description": "Number of rows that failed during the import.", + "example": 5 } } }, - "Domain": { + "ContactImport": { "type": "object", "properties": { "object": { "type": "string", - "description": "The type of object.", - "example": "domain" + "description": "Type of the response object.", + "example": "contact_import" }, "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" + "format": "uuid", + "description": "Unique identifier for the contact import.", + "example": "479e3145-dd38-476b-932c-529ceb705947" }, "status": { "type": "string", "enum": [ - "pending", - "verified", - "failed", - "not_started", - "partially_verified", - "partially_failed" + "queued", + "in_progress", + "completed", + "failed" ], - "description": "The status of the domain.", - "example": "not_started" + "description": "Current status of the contact import.", + "example": "completed" }, "created_at": { "type": "string", "format": "date-time", - "description": "The date and time the domain was created.", - "example": "2023-04-26T20:21:26.347412+00: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." + "description": "Timestamp indicating when the contact import was created.", + "example": "2023-10-06T23:47:56.678Z" }, - "capabilities": { - "$ref": "#/components/schemas/DomainCapabilities" + "completed_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp indicating when the contact import completed.", + "example": "2023-10-06T23:50:56.678Z" }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DomainRecord" - } + "counts": { + "$ref": "#/components/schemas/ContactImportCounts" } } }, - "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" + "GetContactImportResponseSuccess": { + "allOf": [ + { + "$ref": "#/components/schemas/ContactImport" } - } + ] }, - "ListDomainsResponse": { + "ListContactImportsResponseSuccess": { "type": "object", "properties": { "object": { @@ -3567,127 +4784,92 @@ }, "data": { "type": "array", + "description": "Array containing contact imports.", "items": { - "$ref": "#/components/schemas/ListDomainsItem" + "$ref": "#/components/schemas/ContactImport" } } } }, - "ListDomainsItem": { + "CreateBroadcastOptions": { "type": "object", + "required": [ + "from", + "subject", + "segment_id" + ], "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" + "description": "Name of the broadcast." }, - "created_at": { + "segment_id": { "type": "string", - "format": "date-time", - "description": "The date and time the domain was created.", - "example": "2023-04-26T20:21:26.347412+00:00" + "description": "Unique identifier of the segment this broadcast will be sent to." }, - "region": { + "audience_id": { "type": "string", - "description": "The region where the domain is hosted.", - "example": "us-east-1" + "description": "Use `segment_id` instead. Unique identifier of the segment this broadcast will be sent to.", + "deprecated": true }, - "capabilities": { - "$ref": "#/components/schemas/DomainCapabilities" - } - } - }, - "UpdateDomainResponseSuccess": { - "type": "object", - "properties": { - "id": { + "from": { "type": "string", - "description": "The ID of the updated domain.", - "example": "d91cd9bd-1176-453e-8fc1-35364d380206" + "description": "The email address of the sender." }, - "object": { - "type": "string", - "description": "The object type representing the updated domain.", - "example": "domain" - } - } - }, - "DeleteDomainResponse": { - "type": "object", - "properties": { - "object": { + "subject": { "type": "string", - "description": "The type of object.", - "example": "domain" + "description": "The subject line of the email." }, - "id": { - "type": "string", - "description": "The ID of the domain.", - "example": "d91cd9bd-1176-453e-8fc1-35364d380206" + "reply_to": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The email addresses to which replies should be sent." }, - "deleted": { - "type": "boolean", - "description": "Indicates whether the domain was deleted successfully.", - "example": true - } - } - }, - "CreateApiKeyRequest": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { + "preview_text": { "type": "string", - "description": "The API key name." + "description": "The preview text of the email.", + "example": "Here are our announcements" }, - "permission": { + "html": { "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." + "description": "The HTML version of the message." }, - "domain_id": { + "text": { "type": "string", - "description": "Restrict an API key to send emails only from a specific domain. Only used when the permission is sending_access." + "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" } } }, - "CreateApiKeyResponse": { + "CreateBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", - "description": "The ID of the API key." + "description": "The ID of the broadcast.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "token": { + "object": { "type": "string", - "description": "The token of the API key." + "description": "The object type of the response.", + "example": "broadcast" } } }, - "ListApiKeysResponse": { + "ListBroadcastsResponseSuccess": { "type": "object", "properties": { "object": { @@ -3702,368 +4884,777 @@ }, "data": { "type": "array", + "description": "Array containing broadcast information.", "items": { - "$ref": "#/components/schemas/ApiKey" + "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", + "format": "date-time", + "description": "Timestamp indicating when the broadcast was created.", + "example": "2023-10-06T22:59:55.977Z" + }, + "scheduled_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the broadcast is scheduled to be sent.", + "example": "2023-10-06T22:59:55.977Z" + }, + "sent_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the broadcast was sent.", + "example": "2023-10-06T22:59:55.977Z" + }, + "topic_id": { + "type": "string", + "description": "The topic ID that the broadcast is scoped to.", + "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" + } + } } } } }, - "ApiKey": { + "GetBroadcastResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", - "description": "The ID of the API key." + "description": "Unique identifier for the broadcast.", + "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "name": { "type": "string", - "description": "The name of the API key." + "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", "format": "date-time", - "description": "The date and time the API key was created." + "description": "Timestamp indicating when the broadcast was created.", + "example": "2023-10-06T22:59:55.977Z" }, - "last_used_at": { + "scheduled_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the broadcast is scheduled to be sent.", + "example": "2023-10-06T22:59:55.977Z" + }, + "sent_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the broadcast was sent.", + "example": "2023-10-06T22:59:55.977Z" + }, + "text": { "type": [ "string", "null" ], - "format": "date-time", - "description": "The date and time the API key was last used." + "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" } } }, - "DeleteApiKeyResponse": { + "UpdateBroadcastOptions": { "type": "object", "properties": { - "object": { + "name": { "type": "string", - "description": "The type of object.", - "example": "api_key" + "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 API key." + "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": "Indicates whether the API key was successfully deleted.", + "description": "The deleted attribute indicates that the corresponding broadcast has been deleted.", "example": true } } }, - "CreateAudienceOptions": { + "SendBroadcastOptions": { "type": "object", - "deprecated": true, - "required": [ - "name" - ], "properties": { - "name": { + "scheduled_at": { "type": "string", - "description": "The name of the audience you want to create." + "description": "Schedule email to be sent later. The date should be in ISO 8601 format." } } }, - "CreateAudienceResponseSuccess": { + "SendBroadcastResponseSuccess": { "type": "object", - "deprecated": true, "properties": { "id": { "type": "string", - "description": "The ID of the audience.", + "description": "The ID of the broadcast.", "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": { + "RetrievedAttachment": { "type": "object", - "deprecated": true, "properties": { + "object": { + "type": "string", + "description": "The type of object.", + "example": "attachment" + }, "id": { "type": "string", - "description": "The ID of the audience.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "format": "uuid", + "description": "The ID of the attachment.", + "example": "660e8400-e29b-41d4-a716-446655440000" }, - "object": { + "filename": { "type": "string", - "description": "The object of the audience.", - "example": "audience" + "nullable": true, + "description": "The filename of the attachment.", + "example": "document.pdf" }, - "name": { + "content_type": { "type": "string", - "description": "The name of the audience.", - "example": "Registered Users" + "description": "The MIME type of the attachment.", + "example": "application/pdf" }, - "created_at": { + "content_id": { "type": "string", - "description": "The date that the object was created.", - "example": "2023-10-06T22:59:55.977Z" + "description": "The content ID for inline attachments.", + "example": "img001" + }, + "content_disposition": { + "type": "string", + "nullable": true, + "enum": [ + "inline", + "attachment" + ], + "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 } } }, - "RemoveAudienceResponseSuccess": { + "ListAttachmentsResponse": { "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" + "description": "Type of the response object.", + "example": "list" }, - "deleted": { + "has_more": { "type": "boolean", - "description": "The deleted attribute indicates that the corresponding audience has been deleted.", - "example": true + "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", + "nullable": true, + "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", + "nullable": true, + "enum": [ + "inline", + "attachment" + ], + "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 + } + } + } } } }, - "ListAudiencesResponseSuccess": { + "GetReceivedEmailResponse": { "type": "object", - "deprecated": true, "properties": { "object": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "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": [] + }, + "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-06:23:47:56.678Z" }, - "data": { + "attachments": { "type": "array", - "description": "Array containing audience information.", + "description": "Array of attachments.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Unique identifier for the audience.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "format": "uuid", + "description": "The ID of the attachment." }, - "name": { + "filename": { "type": "string", - "description": "Name of the audience.", - "example": "Registered Users" + "nullable": true, + "description": "The filename of the attachment." }, - "created_at": { + "content_type": { "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the audience was created.", - "example": "2023-10-06T22:59:55.977Z" + "description": "The MIME type of the attachment." + }, + "content_id": { + "type": "string", + "description": "The content ID for inline attachments." + }, + "content_disposition": { + "type": "string", + "nullable": true, + "enum": [ + "inline", + "attachment" + ], + "description": "How the attachment should be displayed." + }, + "size": { + "type": "integer", + "description": "Size of the attachment in bytes." } } } } } }, - "CreateContactOptions": { + "ListReceivedEmailsResponse": { "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": { + "object": { "type": "string", - "description": "Last name of the contact.", - "example": "Wozniak" + "description": "Type of the response object.", + "example": "list" }, - "unsubscribed": { + "has_more": { "type": "boolean", - "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", + "description": "Indicates if there are more results available.", "example": false }, - "properties": { - "type": "object", - "additionalProperties": true, - "description": "A map of custom property keys and values to create." - }, - "segments": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Array of segment IDs to add the contact to." - }, - "topics": { + "data": { "type": "array", + "description": "Array containing received email information.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "The topic ID." + "format": "uuid", + "description": "The ID of the received email.", + "example": "550e8400-e29b-41d4-a716-446655440000" }, - "subscription": { + "to": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The recipient email addresses.", + "example": [ + "delivered@resend.dev" + ] + }, + "from": { "type": "string", - "enum": [ - "opt_in", - "opt_out" + "description": "The sender email address.", + "example": "sender@example.com" + }, + "subject": { + "type": [ + "string", + "null" ], - "description": "The subscription status for this topic." + "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", + "nullable": true, + "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", + "nullable": true, + "enum": [ + "inline", + "attachment" + ], + "description": "How the attachment should be displayed." + }, + "size": { + "type": "integer", + "description": "Size of the attachment in bytes." + } + } + } } } - }, - "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": { + "CreateWebhookRequest": { "type": "object", + "required": [ + "endpoint", + "events" + ], "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", - "description": "First name of the contact.", - "example": "Steve" - }, - "last_name": { - "type": "string", - "description": "Last name of the contact.", - "example": "Wozniak" - }, - "created_at": { + "endpoint": { "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the contact was created.", - "example": "2023-10-06T23:47:56.678Z" - }, - "unsubscribed": { - "type": "boolean", - "description": "Indicates if the contact is unsubscribed.", - "example": false + "description": "The URL where webhook events will be sent.", + "example": "https://webhook.example.com/handler" }, - "properties": { - "type": "object", - "additionalProperties": true, - "description": "A map of custom property keys and values." + "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" + ] } } }, - "UpdateContactOptions": { + "CreateWebhookResponse": { "type": "object", "properties": { - "email": { + "object": { "type": "string", - "description": "Email address of the contact.", - "example": "steve.wozniak@gmail.com" + "description": "The type of object.", + "example": "webhook" }, - "first_name": { + "id": { "type": "string", - "description": "First name of the contact.", - "example": "Steve" + "format": "uuid", + "description": "The ID of the webhook.", + "example": "479e3145-dd38-476b-932c-529ceb705947" }, - "last_name": { + "signing_secret": { "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": true, - "description": "A map of custom property keys and values to update." + "description": "The secret key used to verify webhook payloads.", + "example": "whsec_..." } } }, - "UpdateContactResponseSuccess": { + "GetWebhookResponse": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of the response object.", - "example": "contact" + "description": "The type of object.", + "example": "webhook" }, "id": { "type": "string", - "description": "Unique identifier for the updated contact.", + "format": "uuid", + "description": "The ID of the webhook.", "example": "479e3145-dd38-476b-932c-529ceb705947" - } - } - }, - "RemoveContactResponseSuccess": { - "type": "object", - "properties": { - "object": { + }, + "endpoint": { "type": "string", - "description": "Type of the response object.", - "example": "contact" + "description": "The URL where webhook events are sent.", + "example": "https://webhook.example.com/handler" }, - "id": { + "events": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "description": "Array of event types subscribed to.", + "example": [ + "email.sent", + "email.delivered" + ] + }, + "status": { "type": "string", - "description": "Unique identifier for the removed contact.", - "example": "520784e2-887d-4c25-b53c-4ad46ad38100" + "description": "The status of the webhook.", + "example": "enabled" }, - "deleted": { - "type": "boolean", - "description": "Indicates whether the contact was successfully deleted.", - "example": true + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the webhook was created.", + "example": "2023-10-06T23:47:56.678Z" + }, + "signing_secret": { + "type": "string", + "description": "The secret key used to verify webhook payloads.", + "example": "whsec_..." } } }, - "ListContactsResponseSuccess": { + "ListWebhooksResponse": { "type": "object", "properties": { "object": { @@ -4071,672 +5662,615 @@ "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.", + "description": "Array containing webhook information.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Unique identifier for the contact.", - "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" + "format": "uuid", + "description": "The ID of the webhook.", + "example": "479e3145-dd38-476b-932c-529ceb705947" }, - "email": { + "endpoint": { "type": "string", - "description": "Email address of the contact.", - "example": "steve.wozniak@gmail.com" + "description": "The URL where webhook events are sent.", + "example": "https://webhook.example.com/handler" }, - "first_name": { - "type": "string", - "description": "First name of the contact.", - "example": "Steve" + "events": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "description": "Array of event types subscribed to.", + "example": [ + "email.sent" + ] }, - "last_name": { + "status": { "type": "string", - "description": "Last name of the contact.", - "example": "Wozniak" + "description": "The status of the webhook.", + "example": "enabled" }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp indicating when the contact was created.", + "description": "Timestamp indicating when the webhook was created.", "example": "2023-10-06T23:47:56.678Z" - }, - "unsubscribed": { - "type": "boolean", - "description": "Indicates if the contact is unsubscribed.", - "example": false } } } } } }, - "CreateBroadcastOptions": { + "UpdateWebhookRequest": { "type": "object", - "required": [ - "from", - "subject", - "segment_id" - ], "properties": { - "name": { + "endpoint": { "type": "string", - "description": "Name of the broadcast." + "description": "The URL where webhook events will be sent.", + "example": "https://webhook.example.com/new-handler" }, - "segment_id": { - "type": "string", - "description": "Unique identifier of the segment this broadcast will be sent to." + "events": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "description": "Array of event types to subscribe to.", + "example": [ + "email.sent", + "email.delivered" + ] }, - "audience_id": { + "status": { "type": "string", - "description": "Use `segment_id` instead. Unique identifier of the segment this broadcast will be sent to.", - "deprecated": true - }, - "from": { + "enum": [ + "enabled", + "disabled" + ], + "description": "The status of the webhook.", + "example": "enabled" + } + } + }, + "UpdateWebhookResponse": { + "type": "object", + "properties": { + "object": { "type": "string", - "description": "The email address of the sender." + "description": "The type of object.", + "example": "webhook" }, - "subject": { + "id": { "type": "string", - "description": "The subject line of the email." + "format": "uuid", + "description": "The ID of the updated webhook.", + "example": "479e3145-dd38-476b-932c-529ceb705947" + } + } + }, + "DeleteWebhookResponse": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "The type of object.", + "example": "webhook" }, - "reply_to": { - "type": "array", - "items": { - "type": "string" - }, - "description": "The email addresses to which replies should be sent." + "id": { + "type": "string", + "format": "uuid", + "description": "The ID of the deleted webhook.", + "example": "479e3145-dd38-476b-932c-529ceb705947" }, - "preview_text": { + "deleted": { + "type": "boolean", + "description": "Indicates whether the webhook was successfully deleted.", + "example": true + } + } + }, + "TemplateVariable": { + "type": "object", + "properties": { + "id": { "type": "string", - "description": "The preview text of the email.", - "example": "Here are our announcements" + "description": "The ID of the template variable." }, - "html": { + "key": { "type": "string", - "description": "The HTML version of the message." + "description": "The key of the variable." }, - "text": { + "type": { "type": "string", - "description": "The plain text version of the message." + "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": {} + } + ] }, - "topic_id": { + "created_at": { "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" + "format": "date-time", + "description": "Timestamp indicating when the variable was created." }, - "scheduled_at": { + "updated_at": { "type": "string", - "description": "Schedule time to send the broadcast. Can only be used if `send` is true.\n" + "format": "date-time", + "description": "Timestamp indicating when the variable was last updated." } - } + }, + "required": [ + "key", + "type" + ] }, - "CreateBroadcastResponseSuccess": { + "TemplateVariableInput": { "type": "object", "properties": { - "id": { + "key": { "type": "string", - "description": "The ID of the broadcast.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "The key of the variable." }, - "object": { + "type": { "type": "string", - "description": "The object type of the response.", - "example": "broadcast" + "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" + ] }, - "ListBroadcastsResponseSuccess": { + "Template": { "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 + "description": "The type of object.", + "example": "template" }, - "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", - "format": "date-time", - "description": "Timestamp indicating when the broadcast was created.", - "example": "2023-10-06T22:59:55.977Z" - }, - "scheduled_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the broadcast is scheduled to be sent.", - "example": "2023-10-06T22:59:55.977Z" - }, - "sent_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the broadcast was sent.", - "example": "2023-10-06T22:59:55.977Z" - }, - "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" + "description": "The ID of the template." }, - "name": { + "current_version_id": { "type": "string", - "description": "Name of the broadcast.", - "example": "November announcements" + "description": "The ID of the current version of the template." }, - "audience_id": { - "type": [ - "string", - "null" - ], - "description": "Deprecated: use `segment_id` instead. Unique identifier of the segment this broadcast will be sent to.", - "deprecated": true + "name": { + "type": "string", + "description": "The name of the template." }, - "segment_id": { - "type": [ - "string", - "null" - ], - "description": "Unique identifier of the segment this broadcast will be sent to." + "alias": { + "type": "string", + "description": "The alias of the template." }, "from": { "type": "string", - "description": "The email address of the sender.", - "example": "Acme " + "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, "subject": { "type": "string", - "description": "The subject line of the email.", - "example": "Hello World" + "description": "Email subject." }, "reply_to": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "type": "string" }, - "description": "The email addresses to which replies should be sent." + "description": "Reply-to email addresses." }, - "preview_text": { + "html": { "type": "string", - "description": "The preview text of the email.", - "example": "Here are our announcements" + "description": "The HTML version of the template." }, - "status": { + "text": { "type": "string", - "description": "The status of the broadcast.", - "example": "draft" + "description": "The plain text version of the template." + }, + "variables": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateVariable" + } }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp indicating when the broadcast was created.", - "example": "2023-10-06T22:59:55.977Z" + "description": "Timestamp indicating when the template was created." }, - "scheduled_at": { + "updated_at": { "type": "string", "format": "date-time", - "description": "Timestamp indicating when the broadcast is scheduled to be sent.", - "example": "2023-10-06T22:59:55.977Z" + "description": "Timestamp indicating when the template was last updated." + }, + "status": { + "type": "string", + "description": "The publication status of the template.", + "enum": [ + "draft", + "published" + ] + }, + "published_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp indicating when the template was published." + }, + "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." }, - "sent_at": { + "status": { "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the broadcast was sent.", - "example": "2023-10-06T22:59:55.977Z" + "description": "The publication status of the template.", + "enum": [ + "draft", + "published" + ] }, - "text": { + "published_at": { "type": [ "string", "null" ], - "description": "The plain text version of the broadcast content.", - "example": "Hello {{{FIRST_NAME|there}}}!" + "format": "date-time", + "description": "Timestamp indicating when the template was published." }, - "html": { - "type": [ - "string", - "null" - ], - "description": "The HTML version of the broadcast content.", - "example": "

Hello {{{FIRST_NAME|there}}}!

" + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the template was created." }, - "topic_id": { - "type": [ - "string", - "null" - ], - "description": "The topic ID that the broadcast is scoped to.", - "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp indicating when the template was last updated." + }, + "alias": { + "type": "string", + "description": "The alias of the template." } } }, - "UpdateBroadcastOptions": { + "CreateTemplateRequest": { "type": "object", + "required": [ + "name", + "html" + ], "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 + "description": "The name of the template." }, - "segment_id": { + "alias": { "type": "string", - "description": "Unique identifier of the segment this broadcast will be sent to." + "description": "The alias of the template." }, "from": { "type": "string", - "description": "The email address of the sender." + "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, "subject": { "type": "string", - "description": "The subject line of the email." + "description": "Email subject." }, "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." + "description": "Reply-to email addresses." }, "html": { "type": "string", - "description": "The HTML version of the message." + "description": "The HTML version of the template." }, "text": { "type": "string", - "description": "The plain text version of the message." + "description": "The plain text version of the template." }, - "topic_id": { - "type": "string", - "description": "The topic ID that the broadcast will be scoped to." + "variables": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateVariableInput" + } } } }, - "UpdateBroadcastResponseSuccess": { + "CreateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", - "description": "The ID of the broadcast.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", - "example": "broadcast" + "example": "template" } } }, - "RemoveBroadcastResponseSuccess": { + "ListTemplatesResponseSuccess": { "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" + "example": "list" }, - "deleted": { + "data": { + "type": "array", + "description": "Array containing templates information.", + "items": { + "$ref": "#/components/schemas/TemplateListItem" + } + }, + "has_more": { "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" + "description": "Indicates if there are more templates to retrieve." } } }, - "RetrievedAttachment": { + "UpdateTemplateOptions": { "type": "object", "properties": { - "object": { - "type": "string", - "description": "The type of object.", - "example": "attachment" - }, - "id": { + "name": { "type": "string", - "format": "uuid", - "description": "The ID of the attachment.", - "example": "660e8400-e29b-41d4-a716-446655440000" + "description": "The name of the template." }, - "filename": { + "alias": { "type": "string", - "description": "The filename of the attachment.", - "example": "document.pdf" + "description": "The alias of the template." }, - "content_type": { + "from": { "type": "string", - "description": "The MIME type of the attachment.", - "example": "application/pdf" + "description": "Sender email address. To include a friendly name, use the format \"Your Name \"." }, - "content_id": { + "subject": { "type": "string", - "description": "The content ID for inline attachments.", - "example": "img001" + "description": "Email subject." }, - "content_disposition": { - "type": "string", - "enum": [ - "inline", - "attachment" - ], - "description": "How the attachment should be displayed.", - "example": "attachment" + "reply_to": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Reply-to email addresses." }, - "download_url": { + "html": { "type": "string", - "description": "Signed URL to download the attachment content.", - "example": "https://cloudfront.example.com/path?Signature=..." + "description": "The HTML version of the template." }, - "expires_at": { + "text": { "type": "string", - "format": "date-time", - "description": "Timestamp when the download URL expires.", - "example": "2024-10-27T18:30:00.000Z" + "description": "The plain text version of the template." }, - "size": { - "type": "integer", - "description": "Size of the attachment in bytes.", - "example": 2048 + "variables": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateVariableInput" + } } } }, - "ListAttachmentsResponse": { + "UpdateTemplateResponseSuccess": { "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", - "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", - "enum": [ - "inline", - "attachment" - ], - "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 - } - } - } + "id": { + "type": "string", + "description": "The ID of the template." + }, + "object": { + "type": "string", + "description": "The object type of the response.", + "example": "template" } } }, - "GetReceivedEmailResponse": { + "RemoveTemplateResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", - "description": "The type of object.", - "example": "email" + "description": "Type of the response object.", + "example": "template" }, "id": { "type": "string", - "format": "uuid", - "description": "The ID of the received email.", - "example": "550e8400-e29b-41d4-a716-446655440000" + "description": "The ID of the template." }, - "to": { - "type": "array", - "items": { - "type": "string" - }, - "description": "The recipient email addresses.", - "example": [ - "delivered@resend.dev" - ] + "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." }, - "from": { + "object": { "type": "string", - "description": "The sender email address.", - "example": "sender@example.com" + "description": "The object type of the response.", + "example": "template" + } + } + }, + "DuplicateTemplateResponseSuccess": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the duplicated template." }, - "subject": { + "object": { "type": "string", - "description": "The email subject.", - "example": "Hello World" + "description": "The object type of the response.", + "example": "template" + } + } + }, + "CreateSegmentOptions": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the segment." }, - "message_id": { + "audience_id": { "type": "string", - "description": "The unique message ID from the email headers.", - "example": "" + "description": "The ID of the audience this segment belongs to.", + "deprecated": true }, - "bcc": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - }, - "description": "The BCC recipients.", - "example": [] + "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" }, - "cc": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - }, - "description": "The CC recipients.", - "example": [] + "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" }, - "reply_to": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - }, - "description": "The reply-to addresses.", - "example": [] + "object": { + "type": "string", + "description": "The object type.", + "example": "segment" }, - "html": { - "type": [ - "string", - "null" - ], - "description": "The HTML content of the email.", - "example": "

Email content

" + "name": { + "type": "string", + "description": "The name of the segment.", + "example": "Active Users" }, - "text": { - "type": [ - "string", - "null" - ], - "description": "The plain text content of the email.", - "example": "Email content" + "audience_id": { + "type": "string", + "description": "The ID of the audience this segment belongs to.", + "deprecated": true }, - "headers": { - "type": [ - "object", - "null" - ], - "description": "The email headers.", - "example": { - "X-Custom-Header": "value" - } + "filter": { + "type": "object", + "description": "Filter conditions for the segment." }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp when the email was received.", - "example": "2023-10-06:23: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", - "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", - "enum": [ - "inline", - "attachment" - ], - "description": "How the attachment should be displayed." - }, - "size": { - "type": "integer", - "description": "Size of the attachment in bytes." - } - } - } + "description": "Timestamp indicating when the segment was created." } } }, - "ListReceivedEmailsResponse": { + "ListSegmentsResponseSuccess": { "type": "object", "properties": { "object": { @@ -4746,229 +6280,154 @@ }, "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": { + "description": "Indicates if there are more results available." + }, + "data": { + "type": "array", + "description": "Array containing segment information.", + "items": { + "type": "object", + "properties": { + "id": { "type": "string", - "description": "The unique message ID from the email headers.", - "example": "" - }, - "bcc": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - }, - "description": "The BCC recipients." + "description": "Unique identifier for the segment." }, - "cc": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - }, - "description": "The CC recipients." + "name": { + "type": "string", + "description": "Name of the segment." }, - "reply_to": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - }, - "description": "The reply-to addresses." + "audience_id": { + "type": "string", + "description": "The ID of the audience this segment belongs to.", + "deprecated": true }, "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", - "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", - "enum": [ - "inline", - "attachment" - ], - "description": "How the attachment should be displayed." - }, - "size": { - "type": "integer", - "description": "Size of the attachment in bytes." - } - } - } + "description": "Timestamp indicating when the segment was created." } } } } } }, - "CreateWebhookRequest": { + "RemoveSegmentResponseSuccess": { "type": "object", - "required": [ - "endpoint", - "events" - ], "properties": { - "endpoint": { + "id": { "type": "string", - "description": "The URL where webhook events will be sent.", - "example": "https://webhook.example.com/handler" + "description": "The ID of the segment.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "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" - ] + "object": { + "type": "string", + "description": "The object type.", + "example": "segment" + }, + "deleted": { + "type": "boolean", + "description": "Indicates whether the segment was successfully deleted.", + "example": true } } }, - "CreateWebhookResponse": { + "CreateTopicOptions": { "type": "object", + "required": [ + "name", + "default_subscription" + ], "properties": { - "object": { + "name": { "type": "string", - "description": "The type of object.", - "example": "webhook" + "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", - "format": "uuid", - "description": "The ID of the webhook.", - "example": "479e3145-dd38-476b-932c-529ceb705947" + "description": "The ID of the topic.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "signing_secret": { + "object": { "type": "string", - "description": "The secret key used to verify webhook payloads.", - "example": "whsec_..." + "description": "The object type of the response.", + "example": "topic" } } }, - "GetWebhookResponse": { + "GetTopicResponseSuccess": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "The ID of the topic.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + }, "object": { "type": "string", - "description": "The type of object.", - "example": "webhook" + "description": "The object type.", + "example": "topic" }, - "id": { + "name": { "type": "string", - "format": "uuid", - "description": "The ID of the webhook.", - "example": "479e3145-dd38-476b-932c-529ceb705947" + "description": "The name of the topic.", + "example": "Newsletter" }, - "endpoint": { + "description": { "type": "string", - "description": "The URL where webhook events are sent.", - "example": "https://webhook.example.com/handler" + "description": "A description of the topic." }, - "events": { - "type": [ - "array", - "null" + "default_subscription": { + "type": "string", + "enum": [ + "opt_in", + "opt_out" ], - "items": { - "type": "string" - }, - "description": "Array of event types subscribed to.", - "example": [ - "email.sent", - "email.delivered" - ] + "description": "The default subscription status for the topic." }, - "status": { + "visibility": { "type": "string", - "description": "The status of the webhook.", - "example": "enabled" + "enum": [ + "public", + "private" + ], + "description": "The visibility of the topic." }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp indicating when the webhook was created.", - "example": "2023-10-06T23:47:56.678Z" - }, - "signing_secret": { - "type": "string", - "description": "The secret key used to verify webhook payloads.", - "example": "whsec_..." + "description": "Timestamp indicating when the topic was created." } } }, - "ListWebhooksResponse": { + "ListTopicsResponseSuccess": { "type": "object", "properties": { "object": { @@ -4978,973 +6437,832 @@ }, "has_more": { "type": "boolean", - "description": "Indicates if there are more results available.", - "example": false + "description": "Indicates if there are more results available." }, "data": { "type": "array", - "description": "Array containing webhook information.", + "description": "Array containing topic information.", "items": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid", - "description": "The ID of the webhook.", - "example": "479e3145-dd38-476b-932c-529ceb705947" + "description": "Unique identifier for the topic." }, - "endpoint": { + "name": { "type": "string", - "description": "The URL where webhook events are sent.", - "example": "https://webhook.example.com/handler" + "description": "Name of the topic." }, - "events": { - "type": [ - "array", - "null" + "description": { + "type": "string", + "description": "A description of the topic." + }, + "default_subscription": { + "type": "string", + "enum": [ + "opt_in", + "opt_out" ], - "items": { - "type": "string" - }, - "description": "Array of event types subscribed to.", - "example": [ - "email.sent" - ] + "description": "The default subscription status for the topic." }, - "status": { + "visibility": { "type": "string", - "description": "The status of the webhook.", - "example": "enabled" + "enum": [ + "public", + "private" + ], + "description": "The visibility of the topic." }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp indicating when the webhook was created.", - "example": "2023-10-06T23:47:56.678Z" + "description": "Timestamp indicating when the topic was created." } } } } } }, - "UpdateWebhookRequest": { + "UpdateTopicOptions": { "type": "object", "properties": { - "endpoint": { + "name": { "type": "string", - "description": "The URL where webhook events will be sent.", - "example": "https://webhook.example.com/new-handler" + "description": "The name of the topic. Max 50 characters.", + "maxLength": 50 }, - "events": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "description": "Array of event types to subscribe to.", - "example": [ - "email.sent", - "email.delivered" - ] + "description": { + "type": "string", + "description": "A description of the topic. Max 200 characters.", + "maxLength": 200 }, - "status": { + "visibility": { "type": "string", "enum": [ - "enabled", - "disabled" + "public", + "private" ], - "description": "The status of the webhook.", - "example": "enabled" + "description": "The visibility of the topic." } } }, - "UpdateWebhookResponse": { + "UpdateTopicResponseSuccess": { "type": "object", "properties": { - "object": { + "id": { "type": "string", - "description": "The type of object.", - "example": "webhook" + "description": "The ID of the topic.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "id": { + "object": { "type": "string", - "format": "uuid", - "description": "The ID of the updated webhook.", - "example": "479e3145-dd38-476b-932c-529ceb705947" + "description": "The object type.", + "example": "topic" } } }, - "DeleteWebhookResponse": { + "RemoveTopicResponseSuccess": { "type": "object", "properties": { - "object": { + "id": { "type": "string", - "description": "The type of object.", - "example": "webhook" + "description": "The ID of the topic.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "id": { + "object": { "type": "string", - "format": "uuid", - "description": "The ID of the deleted webhook.", - "example": "479e3145-dd38-476b-932c-529ceb705947" + "description": "The object type.", + "example": "topic" }, "deleted": { "type": "boolean", - "description": "Indicates whether the webhook was successfully deleted.", + "description": "Indicates whether the topic was successfully deleted.", "example": true } } }, - "TemplateVariable": { + "CreateContactPropertyOptions": { "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", - "format": "date-time", - "description": "Timestamp indicating when the variable was created." - }, - "updated_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the variable was last updated." - } - }, "required": [ "key", "type" - ] - }, - "TemplateVariableInput": { - "type": "object", + ], "properties": { "key": { "type": "string", - "description": "The key of the variable." + "description": "The property key. Max length is 50 characters. Only alphanumeric characters and underscores are allowed." }, "type": { "type": "string", - "description": "The type of the variable.", "enum": [ "string", - "number", - "boolean", - "object", - "list" - ] + "number" + ], + "description": "The property type." }, "fallback_value": { - "description": "The fallback value of the variable.", "oneOf": [ { "type": "string" }, { "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "object" - }, - { - "type": "array", - "items": {} } - ] + ], + "description": "The default value to use when the property is not set for a contact. Must match the type specified in the type field." } - }, - "required": [ - "key", - "type" - ] + } }, - "Template": { + "CreateContactPropertyResponseSuccess": { "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", - "format": "date-time", - "description": "Timestamp indicating when the template was created." - }, - "updated_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the template was last updated." - }, - "status": { - "type": "string", - "description": "The publication status of the template.", - "enum": [ - "draft", - "published" - ] - }, - "published_at": { - "type": [ - "string", - "null" - ], - "format": "date-time", - "description": "Timestamp indicating when the template was published." + "type": "string", + "description": "The ID of the contact property.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "has_unpublished_versions": { - "type": "boolean", - "description": "Indicates whether the template has unpublished versions." + "object": { + "type": "string", + "description": "The object type of the response.", + "example": "contact_property" } } }, - "TemplateListItem": { + "GetContactPropertyResponseSuccess": { "type": "object", "properties": { + "object": { + "type": "string", + "description": "The object type.", + "example": "contact_property" + }, "id": { "type": "string", - "description": "The ID of the template." + "description": "The ID of the contact property.", + "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" }, - "name": { + "key": { "type": "string", - "description": "The name of the template." + "description": "The property key.", + "example": "company_name" }, - "status": { + "type": { "type": "string", - "description": "The publication status of the template.", - "enum": [ - "draft", - "published" - ] + "description": "The property type.", + "example": "string" }, - "published_at": { - "type": [ - "string", - "null" + "fallback_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + } ], - "format": "date-time", - "description": "Timestamp indicating when the template was published." + "description": "The default value when the property is not set for a contact.", + "example": "Acme Corp" }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp indicating when the template was created." - }, - "updated_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the template was last updated." - }, - "alias": { - "type": "string", - "description": "The alias of the template." + "description": "Timestamp indicating when the contact property was created." } } }, - "CreateTemplateRequest": { + "ListContactPropertiesResponseSuccess": { "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": { + "object": { "type": "string", - "description": "The HTML version of the template." + "description": "Type of the response object.", + "example": "list" }, - "text": { - "type": "string", - "description": "The plain text version of the template." + "has_more": { + "type": "boolean", + "description": "Indicates if there are more results available." }, - "variables": { + "data": { "type": "array", + "description": "Array containing contact property information.", "items": { - "$ref": "#/components/schemas/TemplateVariableInput" + "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", + "format": "date-time", + "description": "Timestamp indicating when the contact property was created." + } + } } } } }, - "CreateTemplateResponseSuccess": { + "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 template." + "description": "The ID of the contact property.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", - "description": "The object type of the response.", - "example": "template" + "description": "The object type.", + "example": "contact_property" } } }, - "ListTemplatesResponseSuccess": { + "RemoveContactPropertyResponseSuccess": { "type": "object", "properties": { - "object": { + "id": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "description": "The ID of the contact property.", + "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, - "data": { - "type": "array", - "description": "Array containing templates information.", - "items": { - "$ref": "#/components/schemas/TemplateListItem" - } + "object": { + "type": "string", + "description": "The object type.", + "example": "contact_property" }, - "has_more": { + "deleted": { "type": "boolean", - "description": "Indicates if there are more templates to retrieve." + "description": "Indicates whether the contact property was successfully deleted.", + "example": true } } }, - "UpdateTemplateOptions": { + "AddContactToSegmentResponseSuccess": { "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": { + "object": { "type": "string", - "description": "Email subject." - }, - "reply_to": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Reply-to email addresses." + "description": "The object type.", + "example": "contact_segment" }, - "html": { + "contact_id": { "type": "string", - "description": "The HTML version of the template." + "description": "The ID of the contact." }, - "text": { + "segment_id": { "type": "string", - "description": "The plain text version of the template." - }, - "variables": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TemplateVariableInput" - } + "description": "The ID of the segment." } } }, - "UpdateTemplateResponseSuccess": { + "ListContactSegmentsResponseSuccess": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "The ID of the template." - }, "object": { "type": "string", - "description": "The object type of the response.", - "example": "template" + "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", + "format": "date-time", + "description": "Timestamp indicating when the contact was added to the segment." + } + } + } } } }, - "RemoveTemplateResponseSuccess": { + "RemoveContactFromSegmentResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of the response object.", - "example": "template" + "description": "The object type.", + "example": "contact_segment" }, - "id": { + "contact_id": { "type": "string", - "description": "The ID of the template." + "description": "The ID of the contact." + }, + "segment_id": { + "type": "string", + "description": "The ID of the segment." }, "deleted": { "type": "boolean", - "description": "Indicates whether the template was successfully deleted.", + "description": "Indicates whether the contact was successfully removed from the segment.", "example": true } } }, - "PublishTemplateResponseSuccess": { + "GetContactTopicsResponseSuccess": { "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." + "description": "Type of the response object.", + "example": "list" }, - "object": { - "type": "string", - "description": "The object type of the response.", - "example": "template" + "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." + } + } + } } } }, - "CreateSegmentOptions": { + "UpdateContactTopicsOptions": { "type": "object", "required": [ - "name" + "topics" ], "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." + "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)." + } + } + } } } }, - "CreateSegmentResponseSuccess": { + "UpdateContactTopicsResponseSuccess": { "type": "object", "properties": { - "id": { + "object": { "type": "string", - "description": "The ID of the segment.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "The object type.", + "example": "contact_topics" }, - "object": { + "contact_id": { "type": "string", - "description": "The object type of the response.", - "example": "segment" + "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." + } + } + } } } }, - "GetSegmentResponseSuccess": { + "LogSummary": { "type": "object", "properties": { "id": { "type": "string", - "description": "The ID of the segment.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "format": "uuid", + "description": "The log ID." }, - "object": { + "created_at": { "type": "string", - "description": "The object type.", - "example": "segment" + "format": "date-time", + "description": "The date the log was created." }, - "name": { + "endpoint": { "type": "string", - "description": "The name of the segment.", - "example": "Active Users" + "description": "The API endpoint that was called." }, - "audience_id": { + "method": { "type": "string", - "description": "The ID of the audience this segment belongs to.", - "deprecated": true + "enum": [ + "GET", + "POST", + "PUT", + "DELETE", + "PATCH", + "OPTIONS" + ], + "description": "The HTTP method used." }, - "filter": { - "type": "object", - "description": "Filter conditions for the segment." + "response_status": { + "type": "integer", + "description": "The HTTP status code of the response." }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the segment was created." + "user_agent": { + "type": [ + "string", + "null" + ], + "description": "The user agent of the request." } } }, - "ListSegmentsResponseSuccess": { + "Log": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", - "example": "list" + "example": "log" }, - "has_more": { - "type": "boolean", - "description": "Indicates if there are more results available." + "id": { + "type": "string", + "format": "uuid", + "description": "The log ID." }, - "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", - "format": "date-time", - "description": "Timestamp indicating when the segment was created." - } - } - } + "created_at": { + "type": "string", + "format": "date-time", + "description": "The date the log was created." + }, + "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." } } }, - "RemoveSegmentResponseSuccess": { + "ListLogsResponse": { "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" + "description": "Type of the response object.", + "example": "list" }, - "deleted": { + "has_more": { "type": "boolean", - "description": "Indicates whether the segment was successfully deleted.", - "example": true + "description": "Indicates if there are more results available.", + "example": false + }, + "data": { + "type": "array", + "description": "Array containing log information.", + "items": { + "$ref": "#/components/schemas/LogSummary" + } } } }, - "CreateTopicOptions": { + "AutomationStep": { "type": "object", + "description": "A step in an automation workflow. The `config` object varies based on the step `type`.", "required": [ - "name", - "default_subscription" + "key", + "type", + "config" ], "properties": { - "name": { + "key": { "type": "string", - "description": "The name of the topic. Max 50 characters.", - "maxLength": 50 + "description": "A unique key for this step within the automation graph." }, - "default_subscription": { + "type": { "type": "string", "enum": [ - "opt_in", - "opt_out" + "trigger", + "send_email", + "delay", + "wait_for_event", + "condition", + "contact_update", + "contact_delete", + "add_to_segment" ], - "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 + "description": "The type of automation step." }, - "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." + "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" } } }, - "CreateTopicResponseSuccess": { + "AutomationStepResponse": { "type": "object", + "description": "A step as returned when retrieving an automation.", "properties": { - "id": { + "key": { "type": "string", - "description": "The ID of the topic.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "The unique key of this step within the automation graph." }, - "object": { + "type": { "type": "string", - "description": "The object type of the response.", - "example": "topic" + "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" } } }, - "GetTopicResponseSuccess": { + "AutomationConnection": { "type": "object", + "description": "A connection between two steps in the automation graph.", + "required": [ + "from", + "to" + ], "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": { + "from": { "type": "string", - "description": "A description of the topic." + "description": "The `key` of the source step." }, - "default_subscription": { + "to": { "type": "string", - "enum": [ - "opt_in", - "opt_out" - ], - "description": "The default subscription status for the topic." + "description": "The `key` of the target step." }, - "visibility": { + "type": { "type": "string", "enum": [ - "public", - "private" + "default", + "condition_met", + "condition_not_met", + "timeout", + "event_received" ], - "description": "The visibility of the topic." - }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the topic was created." + "default": "default", + "description": "The type of connection. Defaults to `default`." } } }, - "ListTopicsResponseSuccess": { + "CreateAutomationRequest": { "type": "object", + "required": [ + "name", + "steps", + "connections" + ], "properties": { - "object": { + "name": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "minLength": 1, + "description": "The name of the automation." }, - "has_more": { - "type": "boolean", - "description": "Indicates if there are more results available." + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "default": "disabled", + "description": "The initial status of the automation. Defaults to `disabled`." }, - "data": { + "steps": { "type": "array", - "description": "Array containing topic information.", + "minItems": 1, + "maxItems": 150, + "description": "The steps that compose the automation workflow. Must include at least one `trigger` step.", "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", - "format": "date-time", - "description": "Timestamp indicating when the topic was created." - } - } + "$ref": "#/components/schemas/AutomationStep" } - } - } - }, - "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." + "connections": { + "type": "array", + "description": "The connections between steps in the automation graph.", + "items": { + "$ref": "#/components/schemas/AutomationConnection" + } } } }, - "UpdateTopicResponseSuccess": { + "CreateAutomationResponse": { "type": "object", "properties": { - "id": { + "object": { "type": "string", - "description": "The ID of the topic.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "Type of the response object.", + "example": "automation" }, - "object": { + "id": { "type": "string", - "description": "The object type.", - "example": "topic" + "description": "The ID of the created automation." } } }, - "RemoveTopicResponseSuccess": { + "Automation": { "type": "object", "properties": { - "id": { + "object": { "type": "string", - "description": "The ID of the topic.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "Type of the response object.", + "example": "automation" }, - "object": { + "id": { "type": "string", - "description": "The object type.", - "example": "topic" + "description": "The ID of the automation." }, - "deleted": { - "type": "boolean", - "description": "Indicates whether the topic was successfully deleted.", - "example": true - } - } - }, - "CreateContactPropertyOptions": { - "type": "object", - "required": [ - "key", - "type" - ], - "properties": { - "key": { + "name": { "type": "string", - "description": "The property key. Max length is 50 characters. Only alphanumeric characters and underscores are allowed." + "description": "The name of the automation." }, - "type": { + "status": { "type": "string", "enum": [ - "string", - "number" + "enabled", + "disabled" ], - "description": "The property type." + "description": "The current status of the automation." }, - "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": { + "created_at": { "type": "string", - "description": "The ID of the contact property.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "The date and time the automation was created." }, - "object": { + "updated_at": { "type": "string", - "description": "The object type of the response.", - "example": "contact_property" + "description": "The date and time the automation was last updated." + }, + "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" + } } } }, - "GetContactPropertyResponseSuccess": { + "AutomationListItem": { "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" + "description": "The ID of the automation." }, - "key": { + "name": { "type": "string", - "description": "The property key.", - "example": "company_name" + "description": "The name of the automation." }, - "type": { + "status": { "type": "string", - "description": "The property type.", - "example": "string" - }, - "fallback_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } + "enum": [ + "enabled", + "disabled" ], - "description": "The default value when the property is not set for a contact.", - "example": "Acme Corp" + "description": "The current status of the automation." }, "created_at": { "type": "string", - "format": "date-time", - "description": "Timestamp indicating when the contact property was created." + "description": "The date and time the automation was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time the automation was last updated." } } }, - "ListContactPropertiesResponseSuccess": { + "ListAutomationsResponse": { "type": "object", "properties": { "object": { @@ -5958,172 +7276,247 @@ }, "data": { "type": "array", - "description": "Array containing contact property information.", + "description": "Array of automations.", "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", - "format": "date-time", - "description": "Timestamp indicating when the contact property was created." - } - } + "$ref": "#/components/schemas/AutomationListItem" } } } }, - "UpdateContactPropertyOptions": { + "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": { - "fallback_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } + "name": { + "type": "string", + "minLength": 1, + "description": "The name of the automation." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" ], - "description": "The default value to use when the property is not set for a contact. Must match the type of the property." + "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" + } } } }, - "UpdateContactPropertyResponseSuccess": { + "PatchAutomationResponse": { "type": "object", "properties": { - "id": { + "object": { "type": "string", - "description": "The ID of the contact property.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "Type of the response object.", + "example": "automation" }, - "object": { + "id": { "type": "string", - "description": "The object type.", - "example": "contact_property" + "description": "The ID of the updated automation." } } }, - "RemoveContactPropertyResponseSuccess": { + "DeleteAutomationResponse": { "type": "object", "properties": { - "id": { + "object": { "type": "string", - "description": "The ID of the contact property.", - "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" + "description": "Type of the response object.", + "example": "automation" }, - "object": { + "id": { "type": "string", - "description": "The object type.", - "example": "contact_property" + "description": "The ID of the deleted automation." }, "deleted": { "type": "boolean", - "description": "Indicates whether the contact property was successfully deleted.", + "description": "Indicates whether the automation was successfully deleted.", "example": true } } }, - "AddContactToSegmentResponseSuccess": { + "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": { - "object": { + "key": { "type": "string", - "description": "The object type.", - "example": "contact_segment" + "description": "The key of the automation step." }, - "contact_id": { + "type": { "type": "string", - "description": "The ID of the contact." + "enum": [ + "trigger", + "send_email", + "delay", + "wait_for_event", + "condition", + "contact_update", + "contact_delete", + "add_to_segment" + ], + "description": "The type of automation step." }, - "segment_id": { + "status": { "type": "string", - "description": "The ID of the segment." + "description": "The execution status of this step." + }, + "started_at": { + "type": [ + "string", + "null" + ], + "description": "The date and time the step started executing." + }, + "completed_at": { + "type": [ + "string", + "null" + ], + "description": "The date and time the step completed executing." + }, + "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." } } }, - "ListContactSegmentsResponseSuccess": { + "AutomationRun": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", - "example": "list" + "example": "automation_run" }, - "has_more": { - "type": "boolean", - "description": "Indicates if there are more results available." + "id": { + "type": "string", + "description": "The ID of the automation run." }, - "data": { + "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." + }, + "completed_at": { + "type": [ + "string", + "null" + ], + "description": "The date and time the run completed." + }, + "created_at": { + "type": "string", + "description": "The date and time the run was created." + }, + "steps": { "type": "array", - "description": "Array containing segment information for this contact.", + "description": "The steps executed in this run, sorted in graph order.", "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", - "format": "date-time", - "description": "Timestamp indicating when the contact was added to the segment." - } - } + "$ref": "#/components/schemas/AutomationRunStep" } } } }, - "RemoveContactFromSegmentResponseSuccess": { + "AutomationRunListItem": { "type": "object", "properties": { - "object": { + "id": { "type": "string", - "description": "The object type.", - "example": "contact_segment" + "description": "The ID of the automation run." }, - "contact_id": { + "status": { "type": "string", - "description": "The ID of the contact." + "enum": [ + "running", + "completed", + "failed", + "cancelled" + ], + "description": "The current status of the automation run." }, - "segment_id": { - "type": "string", - "description": "The ID of the segment." + "started_at": { + "type": [ + "string", + "null" + ], + "description": "The date and time the run started." }, - "deleted": { - "type": "boolean", - "description": "Indicates whether the contact was successfully removed from the segment.", - "example": true + "completed_at": { + "type": [ + "string", + "null" + ], + "description": "The date and time the run completed." + }, + "created_at": { + "type": "string", + "description": "The date and time the run was created." } } }, - "GetContactTopicsResponseSuccess": { + "ListAutomationRunsResponse": { "type": "object", "properties": { "object": { @@ -6137,202 +7530,117 @@ }, "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", + "description": "Array of automation runs.", "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)." - } - } + "$ref": "#/components/schemas/AutomationRunListItem" } } } }, - "UpdateContactTopicsResponseSuccess": { + "Event": { "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", - "format": "date-time", - "description": "The date the log was created." + "description": "Type of the response object.", + "example": "event" }, - "endpoint": { + "id": { "type": "string", - "description": "The API endpoint that was called." + "format": "uuid", + "description": "The event ID." }, - "method": { + "name": { "type": "string", - "enum": [ - "GET", - "POST", - "PUT", - "DELETE", - "PATCH", - "OPTIONS" + "description": "The event name." + }, + "schema": { + "type": [ + "object", + "null" ], - "description": "The HTTP method used." + "description": "A flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." }, - "response_status": { - "type": "integer", - "description": "The HTTP status code of the response." + "created_at": { + "type": "string", + "description": "The date and time the event was created." }, - "user_agent": { + "updated_at": { "type": [ "string", "null" ], - "description": "The user agent of the request." + "description": "The date and time the event was last updated." } } }, - "Log": { + "EventSummary": { "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", - "format": "date-time", - "description": "The date the log was created." + "description": "The event ID." }, - "endpoint": { + "name": { "type": "string", - "description": "The API endpoint that was called." + "description": "The event name." }, - "method": { - "type": "string", - "enum": [ - "GET", - "POST", - "PUT", - "DELETE", - "PATCH", - "OPTIONS" + "schema": { + "type": [ + "object", + "null" ], - "description": "The HTTP method used." + "description": "A flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." }, - "response_status": { - "type": "integer", - "description": "The HTTP status code of the response." + "created_at": { + "type": "string", + "description": "The date and time the event was created." }, - "user_agent": { + "updated_at": { "type": [ "string", "null" ], - "description": "The user agent of the request." + "description": "The date and time the event was last updated." + } + } + }, + "CreateEventRequest": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the event. Cannot start with the reserved `resend:` prefix." }, - "request_body": { + "schema": { "type": [ "object", "null" ], - "description": "The request body sent to the API." + "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" }, - "response_body": { - "type": [ - "object", - "null" - ], - "description": "The response body returned by the API." + "id": { + "type": "string", + "format": "uuid", + "description": "The ID of the created event." } } }, - "ListLogsResponse": { + "ListEventsResponse": { "type": "object", "properties": { "object": { @@ -6347,723 +7655,1018 @@ }, "data": { "type": "array", - "description": "Array containing log information.", + "description": "Array containing event information.", "items": { - "$ref": "#/components/schemas/LogSummary" + "$ref": "#/components/schemas/EventSummary" } } } }, - "AutomationStep": { + "UpdateEventRequest": { "type": "object", - "description": "A step in an automation workflow. The `config` object varies based on the step `type`.", "required": [ - "key", - "type", - "config" + "schema" ], "properties": { - "key": { + "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": "A unique key for this step within the automation graph." + "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": [ - "trigger", - "send_email", - "delay", - "wait_for_event", - "condition", - "contact_update", - "contact_delete", - "add_to_segment" + "Undetermined", + "Transient", + "Permanent" ], - "description": "The type of automation step." + "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." }, - "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" + "link": { + "type": "string", + "description": "The URL that was clicked." + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the click occurred." + }, + "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`)." } } }, - "AutomationStepResponse": { + "WebhookEventSuppressed": { "type": "object", - "description": "A step as returned when retrieving an automation.", + "required": [ + "diagnosticCode", + "message", + "reason", + "type" + ], "properties": { - "key": { + "diagnosticCode": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Array of SMTP diagnostic responses from the receiving server, one entry per recipient." + }, + "message": { "type": "string", - "description": "The unique key of this step within the automation graph." + "description": "Detailed suppression message describing why the email was suppressed." }, - "type": { + "reason": { "type": "string", "enum": [ - "trigger", - "send_email", - "delay", - "wait_for_event", - "condition", - "contact_update", - "contact_delete", - "add_to_segment" + "previous_bounce", + "previous_complaint" ], - "description": "The type of automation step." + "description": "Reason the address is suppressed." }, - "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" + "type": { + "type": "string", + "enum": [ + "Suppressed", + "OnAccountSuppressionList" + ], + "description": "Suppression type." } } }, - "AutomationConnection": { + "WebhookEventAttachment": { "type": "object", - "description": "A connection between two steps in the automation graph.", "required": [ - "from", - "to" + "id" ], "properties": { - "from": { + "id": { "type": "string", - "description": "The `key` of the source step." + "description": "Unique identifier for the attachment." }, - "to": { + "filename": { "type": "string", - "description": "The `key` of the target step." + "description": "The filename of the attachment." }, - "type": { + "content_type": { "type": "string", - "enum": [ - "default", - "condition_met", - "condition_not_met", - "timeout", - "event_received" - ], - "default": "default", - "description": "The type of connection. Defaults to `default`." + "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." } } }, - "CreateAutomationRequest": { + "WebhookDomainRecord": { "type": "object", "required": [ + "record", "name", - "steps", - "connections" + "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", - "minLength": 1, - "description": "The name of the automation." + "description": "DNS record name or subdomain." }, - "status": { + "value": { + "type": "string", + "description": "DNS record value to be set." + }, + "type": { "type": "string", "enum": [ - "enabled", - "disabled" + "MX", + "TXT", + "CNAME", + "CAA" ], - "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" - } + "description": "DNS record type." }, - "connections": { - "type": "array", - "description": "The connections between steps in the automation graph.", - "items": { - "$ref": "#/components/schemas/AutomationConnection" - } - } - } - }, - "CreateAutomationResponse": { - "type": "object", - "properties": { - "object": { + "ttl": { "type": "string", - "description": "Type of the response object.", - "example": "automation" + "description": "Time to live for the DNS record (e.g., `Auto`, `60`)." }, - "id": { + "status": { "type": "string", - "description": "The ID of the created automation." + "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)." } } }, - "Automation": { + "OutboundEmailEventData": { "type": "object", + "required": [ + "email_id", + "created_at", + "from", + "to", + "subject" + ], "properties": { - "object": { + "email_id": { "type": "string", - "description": "Type of the response object.", - "example": "automation" + "description": "Unique identifier for the email." }, - "id": { + "created_at": { "type": "string", - "description": "The ID of the automation." + "format": "date-time", + "description": "Timestamp when the email was created." }, - "name": { + "from": { "type": "string", - "description": "The name of the automation." + "description": "Sender email address and name in the format `Name `." }, - "status": { + "to": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Array of impacted recipient email addresses." + }, + "subject": { "type": "string", - "enum": [ - "enabled", - "disabled" - ], - "description": "The current status of the automation." + "description": "Email subject line." }, - "created_at": { + "broadcast_id": { "type": "string", - "description": "The date and time the automation was created." + "description": "Unique identifier for the broadcast campaign, if applicable." }, - "updated_at": { + "template_id": { "type": "string", - "description": "The date and time the automation was last updated." + "description": "Unique identifier for the template used, if applicable." }, - "steps": { - "type": "array", - "description": "The steps in the active version of the automation.", - "items": { - "$ref": "#/components/schemas/AutomationStepResponse" - } + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Tag key-value pairs associated with the email." }, - "connections": { + "headers": { "type": "array", - "description": "The connections between steps in the active version of the automation.", "items": { - "$ref": "#/components/schemas/AutomationConnection" - } + "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)." } } }, - "AutomationListItem": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the automation." + "EmailBouncedEventData": { + "allOf": [ + { + "$ref": "#/components/schemas/OutboundEmailEventData" }, - "name": { - "type": "string", - "description": "The name of the automation." + { + "type": "object", + "required": [ + "bounce" + ], + "properties": { + "bounce": { + "$ref": "#/components/schemas/WebhookEventBounce" + } + } + } + ] + }, + "EmailClickedEventData": { + "allOf": [ + { + "$ref": "#/components/schemas/OutboundEmailEventData" }, - "status": { - "type": "string", - "enum": [ - "enabled", - "disabled" + { + "type": "object", + "required": [ + "click" ], - "description": "The current status of the automation." + "properties": { + "click": { + "$ref": "#/components/schemas/WebhookEventClick" + } + } + } + ] + }, + "EmailFailedEventData": { + "allOf": [ + { + "$ref": "#/components/schemas/OutboundEmailEventData" }, - "created_at": { - "type": "string", - "description": "The date and time the automation was created." + { + "type": "object", + "required": [ + "failed" + ], + "properties": { + "failed": { + "$ref": "#/components/schemas/WebhookEventFailed" + } + } + } + ] + }, + "EmailSuppressedEventData": { + "allOf": [ + { + "$ref": "#/components/schemas/OutboundEmailEventData" }, - "updated_at": { - "type": "string", - "description": "The date and time the automation was last updated." + { + "type": "object", + "required": [ + "suppressed" + ], + "properties": { + "suppressed": { + "$ref": "#/components/schemas/WebhookEventSuppressed" + } + } } - } + ] }, - "ListAutomationsResponse": { + "EmailReceivedEventData": { "type": "object", + "required": [ + "email_id", + "created_at", + "from", + "to", + "subject", + "message_id", + "bcc", + "cc", + "attachments" + ], "properties": { - "object": { + "email_id": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "description": "Unique identifier for the email." }, - "has_more": { - "type": "boolean", - "description": "Indicates if there are more results available." + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the email was received." }, - "data": { + "from": { + "type": "string", + "description": "Sender email address." + }, + "to": { "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" + }, + "description": "Array of recipient email addresses." + }, + "subject": { "type": "string", - "minLength": 1, - "description": "The name of the automation." + "description": "Email subject line." }, - "status": { + "message_id": { "type": "string", - "enum": [ - "enabled", - "disabled" - ], - "description": "The status of the automation." + "description": "The unique message ID from the email headers." }, - "steps": { + "bcc": { "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" - } + "type": "string" + }, + "description": "BCC recipients." }, - "connections": { + "cc": { "type": "array", - "description": "The connections between steps in the automation graph. Must be provided together with `steps`.", "items": { - "$ref": "#/components/schemas/AutomationConnection" - } + "type": "string" + }, + "description": "CC recipients." + }, + "attachments": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WebhookEventAttachment" + }, + "description": "Array of attachment metadata." } } }, - "PatchAutomationResponse": { + "ContactEventData": { "type": "object", + "required": [ + "id", + "created_at", + "updated_at", + "email", + "unsubscribed" + ], "properties": { - "object": { + "id": { "type": "string", - "description": "Type of the response object.", - "example": "automation" + "description": "Unique identifier for the contact." }, - "id": { + "audience_id": { "type": "string", - "description": "The ID of the updated automation." - } - } - }, - "DeleteAutomationResponse": { - "type": "object", - "properties": { - "object": { + "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", - "description": "Type of the response object.", - "example": "automation" + "format": "date-time", + "description": "Timestamp when the contact was created." }, - "id": { + "updated_at": { "type": "string", - "description": "The ID of the deleted automation." + "format": "date-time", + "description": "Timestamp when the contact was last updated." }, - "deleted": { - "type": "boolean", - "description": "Indicates whether the automation was successfully deleted.", - "example": true - } - } - }, - "StopAutomationResponse": { - "type": "object", - "properties": { - "object": { + "email": { "type": "string", - "description": "Type of the response object.", - "example": "automation" + "description": "Contact's email address." }, - "id": { + "first_name": { "type": "string", - "description": "The ID of the stopped automation." + "description": "Contact's first name." }, - "status": { + "last_name": { "type": "string", - "description": "The status of the automation after stopping.", - "example": "disabled" + "description": "Contact's last name." + }, + "unsubscribed": { + "type": "boolean", + "description": "Whether the contact has unsubscribed from all emails sent from your team." } } }, - "AutomationRunStep": { + "DomainEventData": { "type": "object", - "description": "A step execution within an automation run.", + "required": [ + "id", + "name", + "status", + "created_at", + "region", + "records" + ], "properties": { - "key": { + "id": { "type": "string", - "description": "The key of the automation step." + "description": "Unique identifier for the domain." }, - "type": { + "name": { "type": "string", - "enum": [ - "trigger", - "send_email", - "delay", - "wait_for_event", - "condition", - "contact_update", - "contact_delete", - "add_to_segment" - ], - "description": "The type of automation step." + "description": "The domain name (e.g., `example.com`)." }, "status": { "type": "string", - "description": "The execution status of this step." - }, - "started_at": { - "type": [ - "string", - "null" - ], - "description": "The date and time the step started executing." - }, - "completed_at": { - "type": [ - "string", - "null" + "enum": [ + "verified", + "partially_verified", + "partially_failed", + "failed", + "pending", + "not_started" ], - "description": "The date and time the step completed executing." + "description": "Aggregated verification status of the domain." }, - "output": { - "type": [ - "object", - "null" - ], - "description": "The output produced by the step, if any." + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the domain was created." }, - "error": { - "type": [ - "object", - "null" + "region": { + "type": "string", + "enum": [ + "us-east-1", + "eu-west-1", + "sa-east-1", + "ap-northeast-1" ], - "description": "The error produced by the step, if any." + "description": "AWS region where the domain is configured." }, - "created_at": { - "type": "string", - "description": "The date and time the step record was created." + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WebhookDomainRecord" + }, + "description": "DNS records required for domain verification." } } }, - "AutomationRun": { + "EmailSentEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "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": { "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." - }, - "completed_at": { - "type": [ - "string", - "null" - ], - "description": "The date and time the run completed." + "const": "email.sent", + "description": "The event type." }, "created_at": { "type": "string", - "description": "The date and time the run was created." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "steps": { - "type": "array", - "description": "The steps executed in this run, sorted in graph order.", - "items": { - "$ref": "#/components/schemas/AutomationRunStep" - } + "data": { + "$ref": "#/components/schemas/OutboundEmailEventData" } } }, - "AutomationRunListItem": { + "EmailDeliveredEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "id": { + "type": { "type": "string", - "description": "The ID of the automation run." + "const": "email.delivered", + "description": "The event type." }, - "status": { + "created_at": { "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." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "completed_at": { - "type": [ - "string", - "null" - ], - "description": "The date and time the run completed." + "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", - "description": "The date and time the run was created." + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/OutboundEmailEventData" } } }, - "ListAutomationRunsResponse": { + "EmailBouncedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "const": "email.bounced", + "description": "The event type." }, - "has_more": { - "type": "boolean", - "description": "Indicates if there are more results available." + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was emitted." }, "data": { - "type": "array", - "description": "Array of automation runs.", - "items": { - "$ref": "#/components/schemas/AutomationRunListItem" - } + "$ref": "#/components/schemas/EmailBouncedEventData" } } }, - "Event": { + "EmailComplainedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "event" + "const": "email.complained", + "description": "The event type." }, - "id": { + "created_at": { "type": "string", - "format": "uuid", - "description": "The event ID." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "name": { + "data": { + "$ref": "#/components/schemas/OutboundEmailEventData" + } + } + }, + "EmailOpenedEvent": { + "type": "object", + "required": [ + "type", + "created_at", + "data" + ], + "properties": { + "type": { "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`." + "const": "email.opened", + "description": "The event type." }, "created_at": { "type": "string", - "description": "The date and time the event was created." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "updated_at": { - "type": [ - "string", - "null" - ], - "description": "The date and time the event was last updated." + "data": { + "$ref": "#/components/schemas/OutboundEmailEventData" } } }, - "EventSummary": { + "EmailClickedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "id": { + "type": { "type": "string", - "format": "uuid", - "description": "The event ID." + "const": "email.clicked", + "description": "The event type." }, - "name": { + "created_at": { "type": "string", - "description": "The event name." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "schema": { - "type": [ - "object", - "null" - ], - "description": "A flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." + "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", - "description": "The date and time the event was created." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "updated_at": { - "type": [ - "string", - "null" - ], - "description": "The date and time the event was last updated." + "data": { + "$ref": "#/components/schemas/EmailFailedEventData" } } }, - "CreateEventRequest": { + "EmailScheduledEvent": { "type": "object", "required": [ - "name" + "type", + "created_at", + "data" ], "properties": { - "name": { + "type": { "type": "string", - "description": "The name of the event. Cannot start with the reserved `resend:` prefix." + "const": "email.scheduled", + "description": "The event type." }, - "schema": { - "type": [ - "object", - "null" - ], - "description": "An optional flat key/type map defining the event payload schema. Supported types are `string`, `number`, `boolean`, and `date`." + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/OutboundEmailEventData" } } }, - "CreateEventResponse": { + "EmailSuppressedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "event" + "const": "email.suppressed", + "description": "The event type." }, - "id": { + "created_at": { "type": "string", - "format": "uuid", - "description": "The ID of the created event." + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/EmailSuppressedEventData" } } }, - "ListEventsResponse": { + "EmailReceivedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "list" + "const": "email.received", + "description": "The event type." }, - "has_more": { - "type": "boolean", - "description": "Indicates if there are more results available.", - "example": false + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was emitted." }, "data": { - "type": "array", - "description": "Array containing event information.", - "items": { - "$ref": "#/components/schemas/EventSummary" - } + "$ref": "#/components/schemas/EmailReceivedEventData" } } }, - "UpdateEventRequest": { + "ContactCreatedEvent": { "type": "object", "required": [ - "schema" + "type", + "created_at", + "data" ], "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`." + "type": { + "type": "string", + "const": "contact.created", + "description": "The event type." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/ContactEventData" } } }, - "UpdateEventResponse": { + "ContactUpdatedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "event" + "const": "contact.updated", + "description": "The event type." }, - "id": { + "created_at": { "type": "string", - "format": "uuid", - "description": "The ID of the updated event." + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/ContactEventData" } } }, - "RemoveEventResponse": { + "ContactDeletedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "event" + "const": "contact.deleted", + "description": "The event type." }, - "id": { + "created_at": { "type": "string", - "format": "uuid", - "description": "The ID of the deleted event." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "deleted": { - "type": "boolean", - "description": "Indicates whether the event was deleted.", - "example": true + "data": { + "$ref": "#/components/schemas/ContactEventData" } } }, - "SendEventRequest": { + "DomainCreatedEvent": { "type": "object", "required": [ - "event" + "type", + "created_at", + "data" ], "properties": { - "event": { + "type": { "type": "string", - "description": "The name of the event to send." + "const": "domain.created", + "description": "The event type." }, - "contact_id": { + "created_at": { "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." + "format": "date-time", + "description": "Timestamp when the event was emitted." }, - "email": { + "data": { + "$ref": "#/components/schemas/DomainEventData" + } + } + }, + "DomainUpdatedEvent": { + "type": "object", + "required": [ + "type", + "created_at", + "data" + ], + "properties": { + "type": { "type": "string", - "format": "email", - "description": "The email address to associate with this event. Exactly one of `contact_id` or `email` must be provided." + "const": "domain.updated", + "description": "The event type." }, - "payload": { - "type": "object", - "additionalProperties": true, - "description": "An optional payload of key/value pairs to include with the event." + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/DomainEventData" } } }, - "SendEventResponse": { + "DomainDeletedEvent": { "type": "object", + "required": [ + "type", + "created_at", + "data" + ], "properties": { - "object": { + "type": { "type": "string", - "description": "Type of the response object.", - "example": "event" + "const": "domain.deleted", + "description": "The event type." }, - "event": { + "created_at": { "type": "string", - "description": "The name of the event that was sent." + "format": "date-time", + "description": "Timestamp when the event was emitted." + }, + "data": { + "$ref": "#/components/schemas/DomainEventData" } } }