Resend

v1.5.1 OpenAPI 3.1.2 142 operations source upstream

Resend is the email platform for developers.

Servers

https://api.resend.com

Authentication

bearerAuth http · bearer

Emails

Start sending emails through the Resend API.

Send an email

POST /emails

Header parameters

Idempotency-Key string

A unique identifier for the request to ensure emails are only sent once. Learn more

rules max length 256

Request body SendEmailRequestused by 2 operations

from string

Sender email address. To include a friendly name, use the format "Your Name sender@domain.com".

to one of

Recipient email address. For multiple addresses, send as an array of strings. Max 50.

2 fields

one of · 1 string

one of · 2 array of string

rules min items 1max items 50

1 field

items string

subject string

Email subject.

bcc one of

Bcc recipient email address. For multiple addresses, send as an array of strings.

2 fields

one of · 1 string

one of · 2 array of string

1 field

items string

cc one of

Cc recipient email address. For multiple addresses, send as an array of strings.

2 fields

one of · 1 string

one of · 2 array of string

1 field

items string

reply_to one of

Reply-to email address. For multiple addresses, send as an array of strings.

2 fields

one of · 1 string

one of · 2 array of string

1 field

items string

html string

The HTML version of the message.

text string

The plain text version of the message.

template object

3 fields

id string

The id of the published email template.

variables object

Template variables object with key/value pairs.

1 field

additional properties one of

2 fields

one of · 1 string

one of · 2 number

all of

Use a published template to send the email. If provided, do not include html or text.

headers object

Custom headers to add to the email.

scheduled_at string

Schedule email to be sent later. The date should be in ISO 8601 format.

attachments array of Attachment

1 field

items Attachment

5 fields

content string · binary

Content of an attached file.

filename string

Name of attached file.

path string

Path where the attachment file is hosted

content_type string

Optional content type for the attachment, if not set it will be derived from the filename property

content_id string

Content ID for embedding inline images using cid references (e.g., cid:image001).

tags array of Tag

1 field

items Tag

2 fields

name string

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 string

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.

topic_id string

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.

Responses

200

SendEmailResponse

id string

The ID of the sent email.

POST /emails

{
  "from": "string",
  "to": "string",
  "subject": "string",
  "bcc": "string",
  "cc": "string",
  "reply_to": "string",
  "html": "string",
  "text": "string",
  "template": {
    "id": "string",
    "variables": {
      "variableName": "Sign up now",
      "variableName2": 123
    }
  },
  "headers": {},
  "scheduled_at": "string",
  "attachments": [
    {
      "content": "<binary>",
      "filename": "string",
      "path": "string",
      "content_type": "string",
      "content_id": "string"
    }
  ],
  "tags": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "topic_id": "string"
}

Example generated from the schema

200 Response

{
  "id": "string"
}

Example generated from the schema

Retrieve a single email

GET /emails/{email_id}

Path parameters

email_id string

The ID of the email.

Responses

200

Emailused by 3 operations

object string

The type of object.

id string

The ID of the email.

message_id string

The Message-ID header value of the email.

to array of string

1 field

items string

The email addresses of the recipients.

from string

The email address of the sender.

created_at string

The date and time the email was created.

subject string

The subject line of the email.

html string

The HTML body of the email.

text string

The plain text body of the email.

bcc array of string

The email addresses of the blind carbon copy recipients.

1 field

items string

cc array of string

The email addresses of the carbon copy recipients.

1 field

items string

reply_to array of string

The email addresses to which replies should be sent.

1 field

items string

last_event string

The status of the email.

enum bouncedcanceledclickedcomplaineddelivereddelivery_delayedfailedopenedqueuedscheduledsentsuppressed

200 Response

{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "message_id": "<202301010000.4ef9a417@email.example.com>",
  "to": [
    "delivered@resend.dev"
  ],
  "from": "Acme <onboarding@resend.dev>",
  "created_at": "2023-04-03 22:13:42.674981+00",
  "subject": "Hello World",
  "html": "Congrats on sending your <strong>first email</strong>!",
  "text": "string",
  "bcc": [
    "string"
  ],
  "cc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "last_event": "delivered"
}

Example generated from the schema

Update a single email

PATCH /emails/{email_id}

Path parameters

email_id string

The ID of the email.

Responses

200

UpdateEmailOptions

scheduled_at string

Schedule email to be sent later. The date should be in ISO 8601 format.

Cancel the schedule of the e-mail.

POST /emails/{email_id}/cancel

Path parameters

email_id string

The ID of the email.

Responses

200

Emailused by 3 operations

object string

The type of object.

id string

The ID of the email.

message_id string

The Message-ID header value of the email.

to array of string

1 field

items string

The email addresses of the recipients.

from string

The email address of the sender.

created_at string

The date and time the email was created.

subject string

The subject line of the email.

html string

The HTML body of the email.

text string

The plain text body of the email.

bcc array of string

The email addresses of the blind carbon copy recipients.

1 field

items string

cc array of string

The email addresses of the carbon copy recipients.

1 field

items string

reply_to array of string

The email addresses to which replies should be sent.

1 field

items string

last_event string

The status of the email.

enum bouncedcanceledclickedcomplaineddelivereddelivery_delayedfailedopenedqueuedscheduledsentsuppressed

200 Response

{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "message_id": "<202301010000.4ef9a417@email.example.com>",
  "to": [
    "delivered@resend.dev"
  ],
  "from": "Acme <onboarding@resend.dev>",
  "created_at": "2023-04-03 22:13:42.674981+00",
  "subject": "Hello World",
  "html": "Congrats on sending your <strong>first email</strong>!",
  "text": "string",
  "bcc": [
    "string"
  ],
  "cc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "last_event": "delivered"
}

Example generated from the schema

Create a shareable link for a sent or received email.

POST /emails/{email_id}/share

Path parameters

email_id string

The ID of the email.

Request body ShareEmailOptions

expires_in string

How long the link stays valid for, as a duration like 10m, 2 hours, or 1 day. Defaults to 48h and cannot exceed 48 hours.

Responses

200

ShareEmailResponse

object string

The type of object.

id string

The ID of the email.

url string

The shareable link, valid until it expires.

POST /emails/{email_id}/share

{
  "expires_in": "string"
}

Example generated from the schema

200 Response

{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "url": "https://resend.com/shared?token=eyJhbGciOiJIUzI1NiJ9..."
}

Example generated from the schema

Trigger up to 100 batch emails at once.

POST /emails/batch

Header parameters

Idempotency-Key string

A unique identifier for the request to ensure emails are only sent once. Learn more

rules max length 256

Request body

items SendEmailRequest

14 fields

from string

Sender email address. To include a friendly name, use the format "Your Name sender@domain.com".

to one of

Recipient email address. For multiple addresses, send as an array of strings. Max 50.

2 fields

one of · 1 string

one of · 2 array of string

rules min items 1max items 50

1 field

items string

subject string

Email subject.

bcc one of

Bcc recipient email address. For multiple addresses, send as an array of strings.

2 fields

one of · 1 string

one of · 2 array of string

1 field

items string

cc one of

Cc recipient email address. For multiple addresses, send as an array of strings.

2 fields

one of · 1 string

one of · 2 array of string

1 field

items string

reply_to one of

Reply-to email address. For multiple addresses, send as an array of strings.

2 fields

one of · 1 string

one of · 2 array of string

1 field

items string

html string

The HTML version of the message.

text string

The plain text version of the message.

template object

3 fields

id string

The id of the published email template.

variables object

Template variables object with key/value pairs.

1 field

additional properties one of

2 fields

one of · 1 string

one of · 2 number

all of

Use a published template to send the email. If provided, do not include html or text.

headers object

Custom headers to add to the email.

scheduled_at string

Schedule email to be sent later. The date should be in ISO 8601 format.

attachments array of Attachment

1 field

items Attachment

5 fields

content string · binary

Content of an attached file.

filename string

Name of attached file.

path string

Path where the attachment file is hosted

content_type string

Optional content type for the attachment, if not set it will be derived from the filename property

content_id string

Content ID for embedding inline images using cid references (e.g., cid:image001).

tags array of Tag

1 field

items Tag

2 fields

name string

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 string

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.

topic_id string

Responses

200

CreateBatchEmailsResponse

data array of object

1 field

items object

1 field

id string

The ID of the sent email.

POST /emails/batch

[
  {
    "from": "string",
    "to": "string",
    "subject": "string",
    "bcc": "string",
    "cc": "string",
    "reply_to": "string",
    "html": "string",
    "text": "string",
    "template": {
      "id": "string",
      "variables": {
        "variableName": "Sign up now",
        "variableName2": 123
      }
    },
    "headers": {},
    "scheduled_at": "string",
    "attachments": [
      {
        "content": "<binary>",
        "filename": "string",
        "path": "string",
        "content_type": "string",
        "content_id": "string"
      }
    ],
    "tags": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "topic_id": "string"
  }
]

Example generated from the schema

200 Response

{
  "data": [
    {
      "id": "string"
    }
  ]
}

Example generated from the schema

Retrieve a list of attachments for a sent email

GET /emails/{email_id}/attachments

Path parameters

email_id string · uuid

The ID of the email.

Query parameters

limit integer

Maximum number of attachments to return.

after string · uuid

Pagination cursor to fetch results after this attachment ID. Cannot be used with 'before'.

before string · uuid

Pagination cursor to fetch results before this attachment ID. Cannot be used with 'after'.

Responses

200

ListAttachmentsResponseused by 2 operations

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing attachment information.

1 field

items object

8 fields

id string · uuid

The ID of the attachment.

filename string

nullable

The filename of the attachment.

content_type string

The MIME type of the attachment.

content_id string

The content ID for inline attachments.

content_disposition string

nullable

How the attachment should be displayed.

enum inlineattachmentnull

download_url string

Signed URL to download the attachment content.

expires_at string · date-time

Timestamp when the download URL expires.

size integer

Size of the attachment in bytes.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "content_id": "img001",
      "content_disposition": "attachment",
      "download_url": "https://cloudfront.example.com/path?Signature=...",
      "expires_at": "2024-10-27T18:30:00.000Z",
      "size": 2048
    }
  ]
}

Example generated from the schema

Retrieve a single attachment for a sent email

GET /emails/{email_id}/attachments/{attachment_id}

Path parameters

email_id string · uuid

The ID of the email.

attachment_id string · uuid

The ID of the attachment.

Responses

200

RetrievedAttachmentused by 2 operations

object string

The type of object.

id string · uuid

The ID of the attachment.

filename string

nullable

The filename of the attachment.

content_type string

The MIME type of the attachment.

content_id string

The content ID for inline attachments.

content_disposition string

nullable

How the attachment should be displayed.

enum inlineattachmentnull

download_url string

Signed URL to download the attachment content.

expires_at string · date-time

Timestamp when the download URL expires.

size integer

Size of the attachment in bytes.

200 Response

{
  "object": "attachment",
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "content_type": "application/pdf",
  "content_id": "img001",
  "content_disposition": "attachment",
  "download_url": "https://cloudfront.example.com/path?Signature=...",
  "expires_at": "2024-10-27T18:30:00.000Z",
  "size": 2048
}

Example generated from the schema

Retrieve account-level email metrics

GET /emails/metrics

Query parameters

start_date string

The start of the date range, as an ISO 8601 date or datetime. Must be on or before end_date. Defaults to 6 days before end_date.

end_date string

The end of the date range, as an ISO 8601 date or datetime. Values in the future are clamped to the current time. Defaults to now.

timezone string

The IANA timezone (e.g. America/New_York) used to bucket periods when period is in dimensions.

default UTC

granularity string

The bucket size used when period is in dimensions. The date range can't produce more than 10,000 periods at the chosen granularity.

enum hourlydailyweeklymonthly

default daily

metrics array of string

List of metrics to include in the response. Defaults to all metrics. Accepts a comma-separated value, the parameter repeated, or a mix of both.

1 field

items string

enum receiveddeliveredcomplainedsuppressedbouncedbounced_transientbounced_permanentbounced_undeterminedopenedclickedunsubscribeddelivery_delayedfailedsentunique_openedunique_clickeddelivery_rateopen_rateclick_ratebounce_ratecomplaint_rateunsubscribe_rate

dimensions array of string

List of dimensions to break the response down by. email cannot be combined with broadcast. Defaults to [], returning a single totals row for the whole range, with no data. Accepts a comma-separated value, the parameter repeated, or a mix of both.

1 field

items string

enum perioddomainemailbroadcast

domain_id array of string

List of sending domain IDs to restrict the response to, up to 100. Accepts a comma-separated value, the parameter repeated, or a mix of both.

1 field

items string · uuid

email_id array of string

List of email IDs to restrict the response to, up to 100. Cannot be combined with the broadcast dimension or broadcast_id. Accepts a comma-separated value, the parameter repeated, or a mix of both.

1 field

items string · uuid

broadcast_id array of string

List of broadcast IDs to restrict the response to, up to 100. Cannot be combined with the email dimension or email_id. Accepts a comma-separated value, the parameter repeated, or a mix of both.

1 field

items string · uuid

Responses

200

GetEmailsMetricsResponse

object string

Type of the response object.

start_date string

The start of the requested date range, as an ISO 8601 datetime.

end_date string

The end of the requested date range, as an ISO 8601 datetime.

metrics array of string

The metrics included in the response.

1 field

items string

dimensions array of string

The dimensions the response is broken down by.

1 field

items string

enum perioddomainemailbroadcast

granularity string

The bucket size used when period is in dimensions.

enum hourlydailyweeklymonthly

totals object

The requested metrics, totaled over the whole date range.

1 field

additional properties number

data array of EmailMetricsDataRow

One row per unique combination of the requested dimensions. Omitted when dimensions is empty.

1 field

items EmailMetricsDataRow

A single breakdown row. Which dimension fields are present depends on the requested dimensions; which metric fields are present depends on the requested metrics.

7 fields

period string

Present when period is in dimensions.

domain_id string · uuid

Present when domain is in dimensions.

domain_name string

Present when domain is in dimensions.

email_id string · uuid

Present when email is in dimensions.

broadcast_id string · uuid

Present when broadcast is in dimensions.

broadcast_name string

Present when broadcast is in dimensions.

additional properties number

200 Response

{
  "object": "metrics",
  "start_date": "2026-07-01T00:00:00.000Z",
  "end_date": "2026-07-08T00:00:00.000Z",
  "metrics": [
    "string"
  ],
  "dimensions": [
    "period"
  ],
  "granularity": "hourly",
  "totals": {
    "property1": 0
  },
  "data": [
    {
      "period": "string",
      "domain_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "domain_name": "string",
      "email_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "broadcast_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "broadcast_name": "string"
    }
  ]
}

Example generated from the schema

Domains

Create and manage domains through the Resend API.

Retrieve a list of domains

GET /domains

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListDomainsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of ListDomainsItem

1 field

items ListDomainsItem

8 fields

id string

The ID of the domain.

name string

The name of the domain.

status string

The status of the domain.

enum pendingverifiedfailednot_startedpartially_verifiedpartially_failed

created_at string

The date and time the domain was created.

region string

The region where the domain is hosted.

open_tracking boolean

Whether open tracking is enabled for this domain.

click_tracking boolean

Whether click tracking is enabled for this domain.

capabilities DomainCapabilities

Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.

2 fields

sending string

Enable or disable sending emails from this domain.

enum enableddisabled

receiving string

Enable or disable receiving emails to this domain.

enum enableddisabled

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
      "name": "example.com",
      "status": "not_started",
      "created_at": "2023-04-26 20:21:26.347412+00",
      "region": "us-east-1",
      "open_tracking": false,
      "click_tracking": false,
      "capabilities": {
        "sending": "enabled",
        "receiving": "enabled"
      }
    }
  ]
}

Example generated from the schema

Create a new domain

POST /domains

Request body CreateDomainRequest

name string

The name of the domain you want to create.

region string

The region where emails will be sent from. Possible values are us-east-1 | eu-west-1 | sa-east-1 | ap-northeast-1

enum us-east-1eu-west-1sa-east-1ap-northeast-1

default us-east-1

custom_return_path string

For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld).

open_tracking boolean

Track the open rate of each email.

click_tracking boolean

Track clicks within the body of each HTML email.

tls string

TLS mode. Opportunistic attempts secure connection but falls back to unencrypted. Enforced requires TLS or email won't be sent.

enum opportunisticenforced

default opportunistic

capabilities DomainCapabilities

Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.

2 fields

sending string

Enable or disable sending emails from this domain.

enum enableddisabled

receiving string

Enable or disable receiving emails to this domain.

enum enableddisabled

tracking_subdomain string

The subdomain to use for click and open tracking.

Responses

201

CreateDomainResponse

id string

The ID of the domain.

name string

The name of the domain.

created_at string

The date and time the domain was created.

status string

The status of the domain.

enum pendingverifiedfailednot_startedpartially_verifiedpartially_failed

capabilities DomainCapabilities

Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.

2 fields

sending string

Enable or disable sending emails from this domain.

enum enableddisabled

receiving string

Enable or disable receiving emails to this domain.

enum enableddisabled

records array of DomainRecord

1 field

items DomainRecord

7 fields

record string

The type of record (SPF for sending, DKIM for sending, Receiving for inbound emails, Tracking & TrackingCAA for click and open tracking).

enum SPFDKIMReceivingTrackingTrackingCAA

name string

The name of the DNS record.

type string

The DNS record type.

enum MXTXTCNAMECAA

ttl string

The time to live for the record.

status string

The status of the record.

enum pendingverifiedfailedtemporary_failurenot_started

value string

The value of the record.

priority integer

The priority of the record (only applicable for MX records).

region string

The region where the domain is hosted.

open_tracking boolean

Whether open tracking is enabled for this domain.

click_tracking boolean

Whether click tracking is enabled for this domain.

tracking_subdomain string

The subdomain used for click and open tracking.

POST /domains

{
  "name": "string",
  "region": "us-east-1",
  "custom_return_path": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "tracking_subdomain": "string"
}

Example generated from the schema

201 Response

{
  "id": "string",
  "name": "string",
  "created_at": "2023-10-06 23:47:56.678+00",
  "status": "pending",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "records": [
    {
      "record": "SPF",
      "name": "string",
      "type": "MX",
      "ttl": "string",
      "status": "pending",
      "value": "string",
      "priority": 0
    }
  ],
  "region": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": "string"
}

Example generated from the schema

Retrieve a single domain

GET /domains/{domain_id}

Path parameters

domain_id string

The ID of the domain.

Responses

200

Domain

object string

The type of object.

id string

The ID of the domain.

name string

The name of the domain.

status string

The status of the domain.

enum pendingverifiedfailednot_startedpartially_verifiedpartially_failed

created_at string

The date and time the domain was created.

region string

The region where the domain is hosted.

open_tracking boolean

Whether open tracking is enabled for this domain.

click_tracking boolean

Whether click tracking is enabled for this domain.

tracking_subdomain string

The subdomain used for click and open tracking.

capabilities DomainCapabilities

Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.

2 fields

sending string

Enable or disable sending emails from this domain.

enum enableddisabled

receiving string

Enable or disable receiving emails to this domain.

enum enableddisabled

records array of DomainRecord

1 field

items DomainRecord

7 fields

record string

The type of record (SPF for sending, DKIM for sending, Receiving for inbound emails, Tracking & TrackingCAA for click and open tracking).

enum SPFDKIMReceivingTrackingTrackingCAA

name string

The name of the DNS record.

type string

The DNS record type.

enum MXTXTCNAMECAA

ttl string

The time to live for the record.

status string

The status of the record.

enum pendingverifiedfailedtemporary_failurenot_started

value string

The value of the record.

priority integer

The priority of the record (only applicable for MX records).

200 Response

{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "not_started",
  "created_at": "2023-04-26 20:21:26.347412+00",
  "region": "us-east-1",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": "string",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "records": [
    {
      "record": "SPF",
      "name": "string",
      "type": "MX",
      "ttl": "string",
      "status": "pending",
      "value": "string",
      "priority": 0
    }
  ]
}

Example generated from the schema

Update an existing domain

PATCH /domains/{domain_id}

Path parameters

domain_id string

The ID of the domain.

Request body UpdateDomainOptions

open_tracking boolean

Track the open rate of each email.

click_tracking boolean

Track clicks within the body of each HTML email.

tls string

enforced | opportunistic.

enum opportunisticenforced

default opportunistic

capabilities DomainCapabilities

Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.

2 fields

sending string

Enable or disable sending emails from this domain.

enum enableddisabled

receiving string

Enable or disable receiving emails to this domain.

enum enableddisabled

tracking_subdomain string

The subdomain to use for click and open tracking.

Responses

200

UpdateDomainResponseSuccess

id string

The ID of the updated domain.

object string

The object type representing the updated domain.

PATCH /domains/{domain_id}

{
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "tracking_subdomain": "string"
}

Example generated from the schema

200 Response

{
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "object": "domain"
}

Example generated from the schema

Remove an existing domain

DELETE /domains/{domain_id}

Path parameters

domain_id string

The ID of the domain.

Responses

200

DeleteDomainResponse

object string

The type of object.

id string

The ID of the domain.

deleted boolean

Indicates whether the domain was deleted successfully.

200 Response

{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "deleted": true
}

Example generated from the schema

Verify an existing domain

POST /domains/{domain_id}/verify

Triggers verification of the domain's DNS records including DKIM, SPF, and the tracking CNAME (if a tracking subdomain is configured).

Path parameters

domain_id string

The ID of the domain.

Responses

200

VerifyDomainResponse

object string

The type of object.

id string

The ID of the domain.

200 Response

{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206"
}

Example generated from the schema

Claim a domain

POST /domains/claim

Start a claim for a domain that another Resend account has already verified. The domain is recreated under your account with fresh DKIM keys, so the previous account's DNS records cannot be reused. Returns a TXT record to add to your DNS to prove ownership. Uses the same request body as creating a domain.

Request body CreateDomainClaimRequest

name string

The name of the domain you want to claim.

region string

The region where emails will be sent from. Possible values are us-east-1 | eu-west-1 | sa-east-1 | ap-northeast-1

enum us-east-1eu-west-1sa-east-1ap-northeast-1

default us-east-1

custom_return_path string

For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld).

default send

open_tracking boolean

Track the open rate of each email.

click_tracking boolean

Track clicks within the body of each HTML email.

tracking_subdomain string

The subdomain to use for click and open tracking.

Responses

200 201

An identical pending claim already existed and was returned unchanged.

DomainClaimused by 3 operations

object string

The type of object.

id string

The ID of the claim.

name string

The name of the domain being claimed.

status string

The status of the claim.

enum pendingverifiedcompletedblockedexpiredsupersededcanceledfailed

domain_id string

nullable

The ID of the placeholder domain created for the claim.

region string

nullable

The region where the claimed domain will send from.

enum us-east-1eu-west-1sa-east-1ap-northeast-1null

record DomainClaimRecord

The TXT record to add to your DNS to prove ownership of the claimed domain.

4 fields

type string

The DNS record type. Always TXT for domain claims.

enum TXT

name string

The name of the DNS record (the domain being claimed).

value string

The value of the TXT record.

ttl string

The time to live for the record.

blocked_reason string

nullable

Why the claim is currently blocked, if applicable.

enum grace_periodrecent_owner_activitypending_scheduled_emailsnull

failure_reason string

nullable

Why the claim failed, if applicable.

created_at string

The date and time the claim was created.

expires_at string

The date and time the claim expires if not verified.

Claim created.

DomainClaimused by 3 operations

object string

The type of object.

id string

The ID of the claim.

name string

The name of the domain being claimed.

status string

The status of the claim.

enum pendingverifiedcompletedblockedexpiredsupersededcanceledfailed

domain_id string

nullable

The ID of the placeholder domain created for the claim.

region string

nullable

The region where the claimed domain will send from.

enum us-east-1eu-west-1sa-east-1ap-northeast-1null

record DomainClaimRecord

The TXT record to add to your DNS to prove ownership of the claimed domain.

4 fields

type string

The DNS record type. Always TXT for domain claims.

enum TXT

name string

The name of the DNS record (the domain being claimed).

value string

The value of the TXT record.

ttl string

The time to live for the record.

blocked_reason string

nullable

Why the claim is currently blocked, if applicable.

enum grace_periodrecent_owner_activitypending_scheduled_emailsnull

failure_reason string

nullable

Why the claim failed, if applicable.

created_at string

The date and time the claim was created.

expires_at string

The date and time the claim expires if not verified.

POST /domains/claim

{
  "name": "string",
  "region": "us-east-1",
  "custom_return_path": "send",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": "string"
}

Example generated from the schema

200 Response

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Example generated from the schema

201 Response

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Example generated from the schema

Retrieve a domain claim

GET /domains/{domain_id}/claim

Retrieve the latest claim for the placeholder domain created by the claim.

Path parameters

domain_id string

The ID of the placeholder domain created by the claim.

Responses

200

DomainClaimused by 3 operations

object string

The type of object.

id string

The ID of the claim.

name string

The name of the domain being claimed.

status string

The status of the claim.

enum pendingverifiedcompletedblockedexpiredsupersededcanceledfailed

domain_id string

nullable

The ID of the placeholder domain created for the claim.

region string

nullable

The region where the claimed domain will send from.

enum us-east-1eu-west-1sa-east-1ap-northeast-1null

record DomainClaimRecord

The TXT record to add to your DNS to prove ownership of the claimed domain.

4 fields

type string

The DNS record type. Always TXT for domain claims.

enum TXT

name string

The name of the DNS record (the domain being claimed).

value string

The value of the TXT record.

ttl string

The time to live for the record.

blocked_reason string

nullable

Why the claim is currently blocked, if applicable.

enum grace_periodrecent_owner_activitypending_scheduled_emailsnull

failure_reason string

nullable

Why the claim failed, if applicable.

created_at string

The date and time the claim was created.

expires_at string

The date and time the claim expires if not verified.

200 Response

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Example generated from the schema

Verify a domain claim

POST /domains/{domain_id}/claim/verify

Trigger asynchronous DNS verification and ownership transfer for a domain claim. The claim stays pending while verification runs; poll the retrieve endpoint for status. Once completed, the transferred domain has new DKIM records that must be added to DNS and verified via the standard domain verify endpoint.

Path parameters

domain_id string

The ID of the placeholder domain created by the claim.

Responses

200

DomainClaimused by 3 operations

object string

The type of object.

id string

The ID of the claim.

name string

The name of the domain being claimed.

status string

The status of the claim.

enum pendingverifiedcompletedblockedexpiredsupersededcanceledfailed

domain_id string

nullable

The ID of the placeholder domain created for the claim.

region string

nullable

The region where the claimed domain will send from.

enum us-east-1eu-west-1sa-east-1ap-northeast-1null

record DomainClaimRecord

The TXT record to add to your DNS to prove ownership of the claimed domain.

4 fields

type string

The DNS record type. Always TXT for domain claims.

enum TXT

name string

The name of the DNS record (the domain being claimed).

value string

The value of the TXT record.

ttl string

The time to live for the record.

blocked_reason string

nullable

Why the claim is currently blocked, if applicable.

enum grace_periodrecent_owner_activitypending_scheduled_emailsnull

failure_reason string

nullable

Why the claim failed, if applicable.

created_at string

The date and time the claim was created.

expires_at string

The date and time the claim expires if not verified.

200 Response

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Example generated from the schema

API Keys

Create and manage API Keys through the Resend API.

Retrieve a list of API keys

GET /api-keys

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListApiKeysResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of ApiKey

1 field

items ApiKey

4 fields

id string

The ID of the API key.

name string

The name of the API key.

created_at string

The date and time the API key was created.

last_used_at string

nullable

The date and time the API key was last used.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "name": "string",
      "created_at": "2023-10-06 23:47:56.678+00",
      "last_used_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create a new API key

POST /api-keys

Request body CreateApiKeyRequest

name string

The API key name.

permission string

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.

enum full_accesssending_access

domain_id string

Restrict an API key to send emails only from a specific domain. Only used when the permission is sending_access.

Responses

201

CreateApiKeyResponse

id string

The ID of the API key.

token string

The token of the API key.

POST /api-keys

{
  "name": "string",
  "permission": "full_access",
  "domain_id": "string"
}

Example generated from the schema

201 Response

{
  "id": "string",
  "token": "string"
}

Example generated from the schema

Update an existing API key

PATCH /api-keys/{api_key_id}

Path parameters

api_key_id string

The API key ID.

Request body UpdateApiKeyRequest

name string

The API key name.

Responses

200

UpdateApiKeyResponse

object string

The type of object.

id string

The ID of the API key.

PATCH /api-keys/{api_key_id}

{
  "name": "string"
}

Example generated from the schema

200 Response

{
  "object": "api_key",
  "id": "string"
}

Example generated from the schema

Remove an existing API key

DELETE /api-keys/{api_key_id}

Path parameters

api_key_id string

The API key ID.

Responses

200

DeleteApiKeyResponse

object string

The type of object.

id string

The ID of the API key.

deleted boolean

Indicates whether the API key was successfully deleted.

200 Response

{
  "object": "api_key",
  "id": "string",
  "deleted": true
}

Example generated from the schema

Audiences

Deprecated: Use Segments instead. Create and manage Audiences through the Resend API.

Retrieve a list of audiences deprecated

GET /audiences

Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.

Responses

200

ListAudiencesResponseSuccess

object string

Type of the response object.

data array of object

Array containing audience information.

1 field

items object

3 fields

id string

Unique identifier for the audience.

name string

Name of the audience.

created_at string

Timestamp indicating when the audience was created.

200 Response

{
  "object": "list",
  "data": [
    {
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Registered Users",
      "created_at": "2023-10-06 22:59:55.977+00"
    }
  ]
}

Example generated from the schema

Create a list of contacts deprecated

POST /audiences

Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.

Request body CreateAudienceOptions

name string

The name of the audience you want to create.

Responses

201

CreateAudienceResponseSuccess

id string

The ID of the audience.

object string

The object of the audience.

name string

The name of the audience.

POST /audiences

{
  "name": "string"
}

Example generated from the schema

201 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "audience",
  "name": "Registered Users"
}

Example generated from the schema

Retrieve a single audience deprecated

GET /audiences/{id}

Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.

Path parameters

id string

The Audience ID.

Responses

200

GetAudienceResponseSuccess

id string

The ID of the audience.

object string

The object of the audience.

name string

The name of the audience.

created_at string

The date that the object was created.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "audience",
  "name": "Registered Users",
  "created_at": "2023-10-06 22:59:55.977+00"
}

Example generated from the schema

Remove an existing audience deprecated

DELETE /audiences/{id}

Deprecated: Use Segments instead. These endpoints still work, but will be removed in the future.

Path parameters

id string

The Audience ID.

Responses

200

RemoveAudienceResponseSuccess

id string

The ID of the audience.

object string

The object of the audience.

deleted boolean

The deleted attribute indicates that the corresponding audience has been deleted.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "audience",
  "deleted": true
}

Example generated from the schema

Contacts

Create and manage Contacts through the Resend API.

Retrieve a list of contacts

GET /contacts

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListContactsResponseSuccessused by 2 operations

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing contact information.

1 field

items object

6 fields

id string

Unique identifier for the contact.

email string

Email address of the contact.

first_name string

nullable

First name of the contact.

last_name string

nullable

Last name of the contact.

created_at string

Timestamp indicating when the contact was created.

unsubscribed boolean

Indicates if the contact is unsubscribed.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "steve.wozniak@gmail.com",
      "first_name": "Steve",
      "last_name": "Wozniak",
      "created_at": "2023-10-06 23:47:56.678+00",
      "unsubscribed": false
    }
  ]
}

Example generated from the schema

Create a new contact

POST /contacts

Request body CreateContactOptions

email string

Email address of the contact.

first_name string

First name of the contact.

last_name string

Last name of the contact.

unsubscribed boolean

The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.

properties object

A map of custom property keys and values to create.

1 field

additional properties string | number

nullable

segments array of object

Array of segment IDs to add the contact to.

1 field

items object

1 field

id string

The segment ID

topics array of object

Array of topic subscriptions for the contact.

1 field

items object

2 fields

id string

The topic ID.

subscription string

The subscription status for this topic.

enum opt_inopt_out

audience_id string

deprecated

Unique identifier of the audience to which the contact belongs.

Responses

201

CreateContactResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the created contact.

POST /contacts

{
  "email": "steve.wozniak@gmail.com",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "unsubscribed": false,
  "properties": {
    "property1": "string"
  },
  "segments": [
    {
      "id": "string"
    }
  ],
  "topics": [
    {
      "id": "string",
      "subscription": "opt_in"
    }
  ],
  "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
}

Example generated from the schema

201 Response

{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Example generated from the schema

Retrieve a list of contact imports

GET /contacts/imports

Query parameters

status string

Filter contact imports by status.

enum queuedin_progresscompletedfailed

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListContactImportsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of ContactImport

Array containing contact imports.

1 field

items ContactImport

6 fields

object string

Type of the response object.

id string · uuid

Unique identifier for the contact import.

status string

Current status of the contact import.

enum queuedin_progresscompletedfailed

created_at string

Timestamp indicating when the contact import was created.

completed_at string

nullable

Timestamp indicating when the contact import completed.

counts ContactImportCounts

5 fields

total integer

Total number of rows processed by the import.

created integer

Number of contacts created by the import.

updated integer

Number of contacts updated by the import.

skipped integer

Number of rows skipped by the import.

failed integer

Number of rows that failed during the import.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_import",
      "id": "479e3145-dd38-476b-932c-529ceb705947",
      "status": "completed",
      "created_at": "2023-10-06 23:47:56.678+00",
      "completed_at": "2023-10-06 23:50:56.678+00",
      "counts": {
        "total": 100,
        "created": 80,
        "updated": 10,
        "skipped": 5,
        "failed": 5
      }
    }
  ]
}

Example generated from the schema

Create a contact import

POST /contacts/imports

Request body CreateContactImportOptionsmultipart/form-data

file string · binary

CSV file to import. Maximum size is 50MB.

column_map string

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.

on_conflict string

Strategy to use when an imported contact already exists.

enum upsertskip

default skip

segments string

JSON-encoded array of segments to add imported contacts to.

topics string

JSON-encoded array of topic subscriptions to apply to imported contacts. Each subscription must be opt_in or opt_out.

Responses

201

CreateContactImportResponseSuccess

object string

Type of the response object.

id string · uuid

Unique identifier for the created contact import.

POST /contacts/imports

Content-Type: multipart/form-data

{
  "file": "<binary>",
  "column_map": "{\"email\":\"Email\",\"first_name\":\"First Name\",\"last_name\":\"Last Name\",\"unsubscribed\":\"Unsubscribed\",\"properties\":{\"plan\":{\"column\":\"Plan\",\"type\":\"string\"}}}",
  "on_conflict": "skip",
  "segments": "[{\"id\":\"78261eea-8f8b-4381-83c6-79fa7120f1cf\"}]",
  "topics": "[{\"id\":\"b6d24b8e-af0b-4c3c-be0c-359bbd97381e\",\"subscription\":\"opt_in\"}]"
}

Example generated from the schema

201 Response

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Example generated from the schema

Retrieve a single contact import

GET /contacts/imports/{id}

Path parameters

id string · uuid

The Contact Import ID.

Responses

200

GetContactImportResponseSuccess

object string

Type of the response object.

id string · uuid

Unique identifier for the contact import.

status string

Current status of the contact import.

enum queuedin_progresscompletedfailed

created_at string

Timestamp indicating when the contact import was created.

completed_at string

nullable

Timestamp indicating when the contact import completed.

counts ContactImportCounts

5 fields

total integer

Total number of rows processed by the import.

created integer

Number of contacts created by the import.

updated integer

Number of contacts updated by the import.

skipped integer

Number of rows skipped by the import.

failed integer

Number of rows that failed during the import.

200 Response

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "status": "completed",
  "created_at": "2023-10-06 23:47:56.678+00",
  "completed_at": "2023-10-06 23:50:56.678+00",
  "counts": {
    "total": 100,
    "created": 80,
    "updated": 10,
    "skipped": 5,
    "failed": 5
  }
}

Example generated from the schema

Retrieve a single contact by ID or email

GET /contacts/{id}

Path parameters

id string

The Contact ID or email address.

Responses

200

GetContactResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the contact.

email string

Email address of the contact.

first_name string

nullable

First name of the contact.

last_name string

nullable

Last name of the contact.

created_at string

Timestamp indicating when the contact was created.

unsubscribed boolean

Indicates if the contact is unsubscribed.

properties object

A map of custom property keys and values.

200 Response

{
  "object": "contact",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "steve.wozniak@gmail.com",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "created_at": "2023-10-06 23:47:56.678+00",
  "unsubscribed": false,
  "properties": {}
}

Example generated from the schema

Update a single contact by ID or email

PATCH /contacts/{id}

Path parameters

id string

The Contact ID or email address.

Request body UpdateContactOptions

email string

Email address of the contact.

first_name string

First name of the contact.

last_name string

Last name of the contact.

unsubscribed boolean

The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.

properties object

A map of custom property keys and values to update.

1 field

additional properties string | number | boolean

nullable

Responses

200

UpdateContactResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the updated contact.

PATCH /contacts/{id}

{
  "email": "steve.wozniak@gmail.com",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "unsubscribed": false,
  "properties": {
    "property1": "string"
  }
}

Example generated from the schema

200 Response

{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Example generated from the schema

Remove an existing contact by ID or email

DELETE /contacts/{id}

Path parameters

id string

The Contact ID or email address.

Responses

200

RemoveContactResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the removed contact.

deleted boolean

Indicates whether the contact was successfully deleted.

200 Response

{
  "object": "contact",
  "id": "520784e2-887d-4c25-b53c-4ad46ad38100",
  "deleted": true
}

Example generated from the schema

Retrieve a list of segments for a contact

GET /contacts/{contact_id}/segments

Path parameters

contact_id string

The Contact ID or email address.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListContactSegmentsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing segment information for this contact.

1 field

items object

3 fields

id string

Unique identifier for the segment.

name string

Name of the segment.

created_at string

Timestamp indicating when the contact was added to the segment.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "name": "string",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Add a contact to a segment

POST /contacts/{contact_id}/segments/{segment_id}

Path parameters

contact_id string

The Contact ID or email address.

segment_id string

The Segment ID.

Responses

200

AddContactToSegmentResponseSuccess

object string

The object type.

contact_id string

The ID of the contact.

segment_id string

The ID of the segment.

200 Response

{
  "object": "contact_segment",
  "contact_id": "string",
  "segment_id": "string"
}

Example generated from the schema

Remove a contact from a segment

DELETE /contacts/{contact_id}/segments/{segment_id}

Path parameters

contact_id string

The Contact ID or email address.

segment_id string

The Segment ID.

Responses

200

RemoveContactFromSegmentResponseSuccess

object string

The object type.

contact_id string

The ID of the contact.

segment_id string

The ID of the segment.

deleted boolean

Indicates whether the contact was successfully removed from the segment.

200 Response

{
  "object": "contact_segment",
  "contact_id": "string",
  "segment_id": "string",
  "deleted": true
}

Example generated from the schema

Retrieve topics for a contact

GET /contacts/{contact_id}/topics

Path parameters

contact_id string

The Contact ID or email address.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

GetContactTopicsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing topic subscriptions for this contact.

1 field

items object

4 fields

id string

Unique identifier for the topic.

name string

Name of the topic.

description string

Description of the topic.

subscription string

The subscription status for this topic.

enum opt_inopt_out

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "subscription": "opt_in"
    }
  ]
}

Example generated from the schema

Update topics for a contact

PATCH /contacts/{contact_id}/topics

Path parameters

contact_id string

The Contact ID or email address.

Request body UpdateContactTopicsOptions

topics array of object

1 field

items object

2 fields

id string

The ID of the topic.

subscription string

The subscription status (opt_in or opt_out).

enum opt_inopt_out

Responses

200

UpdateContactTopicsResponseSuccess

object string

The object type.

contact_id string

The ID of the contact.

topics array of object

Array of updated topic subscriptions.

1 field

items object

2 fields

id string

The ID of the topic.

subscription string

The subscription status.

enum opt_inopt_out

PATCH /contacts/{contact_id}/topics

{
  "topics": [
    {
      "id": "string",
      "subscription": "opt_in"
    }
  ]
}

Example generated from the schema

200 Response

{
  "object": "contact_topics",
  "contact_id": "string",
  "topics": [
    {
      "id": "string",
      "subscription": "opt_in"
    }
  ]
}

Example generated from the schema

Receiving Emails

Retrieve and manage received emails and attachments through the Resend API.

Retrieve a list of received emails

GET /emails/receiving

Query parameters

limit integer

Maximum number of received emails to return.

after string · uuid

Pagination cursor to fetch results after this email ID. Cannot be used with 'before'.

before string · uuid

Pagination cursor to fetch results before this email ID. Cannot be used with 'after'.

Responses

200

ListReceivedEmailsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing received email information.

1 field

items object

10 fields

id string · uuid

The ID of the received email.

to array of string

The recipient email addresses.

1 field

items string

from string

The sender email address.

subject string

nullable

The email subject.

message_id string

The unique message ID from the email headers.

bcc array of string

nullable

The BCC recipients.

1 field

items string

cc array of string

nullable

The CC recipients.

1 field

items string

reply_to array of string

nullable

The reply-to addresses.

1 field

items string

created_at string · date-time

Timestamp when the email was received.

attachments array of object

Array of attachments for this email.

1 field

items object

6 fields

id string · uuid

The ID of the attachment.

filename string

nullable

The filename of the attachment.

content_type string

The MIME type of the attachment.

content_id string

The content ID for inline attachments.

content_disposition string

nullable

How the attachment should be displayed.

enum inlineattachmentnull

size integer

Size of the attachment in bytes.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "to": [
        "delivered@resend.dev"
      ],
      "from": "sender@example.com",
      "subject": "Hello World",
      "message_id": "<message-id@email.example.com>",
      "bcc": [
        "string"
      ],
      "cc": [
        "string"
      ],
      "reply_to": [
        "string"
      ],
      "created_at": "2023-10-06T23:47:56.678Z",
      "attachments": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "filename": "string",
          "content_type": "string",
          "content_id": "string",
          "content_disposition": "inline",
          "size": 0
        }
      ]
    }
  ]
}

Example generated from the schema

Retrieve a single received email

GET /emails/receiving/{email_id}

Path parameters

email_id string · uuid

The ID of the received email.

Responses

200

GetReceivedEmailResponse

object string

The type of object.

id string · uuid

The ID of the received email.

to array of string

The recipient email addresses.

1 field

items string

from string

The sender email address.

subject string

The email subject.

message_id string

The unique message ID from the email headers.

bcc array of string

nullable

The BCC recipients.

1 field

items string

cc array of string

nullable

The CC recipients.

1 field

items string

reply_to array of string

nullable

The reply-to addresses.

1 field

items string

received_for array of string

The recipient addresses the email was forwarded for, taken from the for clause of the message's Received headers.

1 field

items string

html string

nullable

The HTML content of the email.

text string

nullable

The plain text content of the email.

headers object

nullable

The email headers.

created_at string · date-time

Timestamp when the email was received.

attachments array of object

Array of attachments.

1 field

items object

6 fields

id string · uuid

The ID of the attachment.

filename string

nullable

The filename of the attachment.

content_type string

The MIME type of the attachment.

content_id string

The content ID for inline attachments.

content_disposition string

nullable

How the attachment should be displayed.

enum inlineattachmentnull

size integer

Size of the attachment in bytes.

200 Response

{
  "object": "email",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "to": [
    "delivered@resend.dev"
  ],
  "from": "sender@example.com",
  "subject": "Hello World",
  "message_id": "<message-id@email.example.com>",
  "bcc": [],
  "cc": [],
  "reply_to": [],
  "received_for": [
    "forwarded@example.com"
  ],
  "html": "<p>Email content</p>",
  "text": "Email content",
  "headers": {
    "X-Custom-Header": "value"
  },
  "created_at": "2023-10-06T23:47:56.678Z",
  "attachments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "filename": "string",
      "content_type": "string",
      "content_id": "string",
      "content_disposition": "inline",
      "size": 0
    }
  ]
}

Example generated from the schema

Retrieve a list of attachments for a received email

GET /emails/receiving/{email_id}/attachments

Path parameters

email_id string · uuid

The ID of the received email.

Query parameters

limit integer

Maximum number of attachments to return.

after string · uuid

Pagination cursor to fetch results after this attachment ID. Cannot be used with 'before'.

before string · uuid

Pagination cursor to fetch results before this attachment ID. Cannot be used with 'after'.

Responses

200

ListAttachmentsResponseused by 2 operations

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing attachment information.

1 field

items object

8 fields

id string · uuid

The ID of the attachment.

filename string

nullable

The filename of the attachment.

content_type string

The MIME type of the attachment.

content_id string

The content ID for inline attachments.

content_disposition string

nullable

How the attachment should be displayed.

enum inlineattachmentnull

download_url string

Signed URL to download the attachment content.

expires_at string · date-time

Timestamp when the download URL expires.

size integer

Size of the attachment in bytes.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "content_id": "img001",
      "content_disposition": "attachment",
      "download_url": "https://cloudfront.example.com/path?Signature=...",
      "expires_at": "2024-10-27T18:30:00.000Z",
      "size": 2048
    }
  ]
}

Example generated from the schema

Retrieve a single attachment for a received email

GET /emails/receiving/{email_id}/attachments/{attachment_id}

Path parameters

email_id string · uuid

The ID of the received email.

attachment_id string · uuid

The ID of the attachment.

Responses

200

RetrievedAttachmentused by 2 operations

object string

The type of object.

id string · uuid

The ID of the attachment.

filename string

nullable

The filename of the attachment.

content_type string

The MIME type of the attachment.

content_id string

The content ID for inline attachments.

content_disposition string

nullable

How the attachment should be displayed.

enum inlineattachmentnull

download_url string

Signed URL to download the attachment content.

expires_at string · date-time

Timestamp when the download URL expires.

size integer

Size of the attachment in bytes.

200 Response

{
  "object": "attachment",
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "content_type": "application/pdf",
  "content_id": "img001",
  "content_disposition": "attachment",
  "download_url": "https://cloudfront.example.com/path?Signature=...",
  "expires_at": "2024-10-27T18:30:00.000Z",
  "size": 2048
}

Example generated from the schema

Webhooks

Create and manage Webhooks through the Resend API.

Retrieve a list of webhooks

GET /webhooks

Query parameters

limit integer

Maximum number of webhooks to return.

after string · uuid

Pagination cursor to fetch results after this webhook ID. Cannot be used with 'before'.

before string · uuid

Pagination cursor to fetch results before this webhook ID. Cannot be used with 'after'.

Responses

200

ListWebhooksResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing webhook information.

1 field

items object

5 fields

id string · uuid

The ID of the webhook.

endpoint string

The URL where webhook events are sent.

events array of string

nullable

Array of event types subscribed to.

1 field

items string

status string

The status of the webhook.

created_at string

Timestamp indicating when the webhook was created.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "479e3145-dd38-476b-932c-529ceb705947",
      "endpoint": "https://webhook.example.com/handler",
      "events": [
        "email.sent"
      ],
      "status": "enabled",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create a new webhook

POST /webhooks

Request body CreateWebhookRequest

endpoint string

The URL where webhook events will be sent.

events array of string

Array of event types to subscribe to.

rules min items 1

1 field

items string

Responses

201

Created

CreateWebhookResponse

object string

The type of object.

id string · uuid

The ID of the webhook.

signing_secret string

The secret key used to verify webhook payloads.

POST /webhooks

{
  "endpoint": "https://webhook.example.com/handler",
  "events": [
    "email.sent",
    "email.delivered",
    "email.bounced",
    "email.suppressed"
  ]
}

Example generated from the schema

201 Response

{
  "object": "webhook",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "signing_secret": "whsec_..."
}

Example generated from the schema

Retrieve a single webhook

GET /webhooks/{webhook_id}

Path parameters

webhook_id string · uuid

The Webhook ID.

Responses

200

GetWebhookResponse

object string

The type of object.

id string · uuid

The ID of the webhook.

endpoint string

The URL where webhook events are sent.

events array of string

nullable

Array of event types subscribed to.

1 field

items string

status string

The status of the webhook.

created_at string

Timestamp indicating when the webhook was created.

signing_secret string

The secret key used to verify webhook payloads.

200 Response

{
  "object": "webhook",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "endpoint": "https://webhook.example.com/handler",
  "events": [
    "email.sent",
    "email.delivered"
  ],
  "status": "enabled",
  "created_at": "2023-10-06 23:47:56.678+00",
  "signing_secret": "whsec_..."
}

Example generated from the schema

Update an existing webhook

PATCH /webhooks/{webhook_id}

Path parameters

webhook_id string · uuid

The Webhook ID.

Request body UpdateWebhookRequest

endpoint string

The URL where webhook events will be sent.

events array of string

Array of event types to subscribe to.

rules min items 1

1 field

items string

status string

The status of the webhook.

enum enableddisabled

Responses

200

UpdateWebhookResponse

object string

The type of object.

id string · uuid

The ID of the updated webhook.

PATCH /webhooks/{webhook_id}

{
  "endpoint": "https://webhook.example.com/new-handler",
  "events": [
    "email.sent",
    "email.delivered"
  ],
  "status": "enabled"
}

Example generated from the schema

200 Response

{
  "object": "webhook",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Example generated from the schema

Remove an existing webhook

DELETE /webhooks/{webhook_id}

Path parameters

webhook_id string · uuid

The Webhook ID.

Responses

200

DeleteWebhookResponse

object string

The type of object.

id string · uuid

The ID of the deleted webhook.

deleted boolean

Indicates whether the webhook was successfully deleted.

200 Response

{
  "object": "webhook",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "deleted": true
}

Example generated from the schema

Rotate a webhook signing secret

POST /webhooks/{webhook_id}/signing-secret/rotate

Generates a new signing secret for the webhook and returns it. Payloads delivered after the rotation are signed with the new secret. The previous secret keeps verifying payloads for 24 hours, so both secrets are accepted during that window. A webhook that does not exist or was removed returns a 404 not_found.

Path parameters

webhook_id string · uuid

The Webhook ID.

Responses

200

RotateWebhookSigningSecretResponse

object string

The type of object.

id string · uuid

The ID of the webhook.

signing_secret string

The new secret key used to verify webhook payloads.

200 Response

{
  "object": "webhook",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "signing_secret": "whsec_..."
}

Example generated from the schema

Retrieve a list of webhook events

GET /webhooks/{webhook_id}/events

Path parameters

webhook_id string · uuid

The Webhook ID.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

Responses

200

ListWebhookEventsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing webhook event information.

1 field

items object

4 fields

id string

The ID of the webhook event.

type string

The type of the event.

created_at string · date-time

Timestamp indicating when the event was created.

status string

The delivery status of the event for this webhook.

enum pendingattemptingsuccessfailed

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2",
      "type": "email.sent",
      "created_at": "2026-08-22T15:28:00.000Z",
      "status": "success"
    }
  ]
}

Example generated from the schema

Retrieve a single webhook event

GET /webhooks/{webhook_id}/events/{event_id}

Path parameters

webhook_id string · uuid

The Webhook ID.

event_id string

The Webhook Event ID.

Responses

200

GetWebhookEventResponse

object string

The type of object.

id string

The ID of the webhook event.

type string

The type of the event.

created_at string · date-time

Timestamp indicating when the event was created.

status string

The delivery status of the event for this webhook.

enum pendingattemptingsuccessfailed

next_attempt_at string · date-time

nullable

Timestamp of the next scheduled delivery attempt, or null when none is scheduled. Always null once the event has succeeded or permanently failed.

payload object

The event payload sent to the webhook endpoint.

200 Response

{
  "object": "webhook_event",
  "id": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2",
  "type": "email.sent",
  "created_at": "2026-08-22T15:28:00.000Z",
  "status": "attempting",
  "next_attempt_at": "2026-08-22T15:33:00.000Z",
  "payload": {
    "type": "email.sent",
    "created_at": "2026-08-22T15:28:00.000Z",
    "data": {
      "email_id": "571f1f42-1c2d-4b1f-8f8e-8b3b5b3b5b3b",
      "from": "onboarding@resend.dev",
      "to": [
        "delivered@resend.dev"
      ],
      "subject": "Welcome",
      "created_at": "2026-08-22T15:27:59.000Z"
    }
  }
}

Example generated from the schema

Replay a webhook event

POST /webhooks/{webhook_id}/events/{event_id}/replay

Queues one more delivery of the event to the webhook. The event must be retrievable through the get event endpoint and the webhook must be enabled; a disabled webhook returns a 422 validation_error. A manual replay does not schedule automatic retries.

Path parameters

webhook_id string · uuid

The Webhook ID.

event_id string

The Webhook Event ID.

Responses

200

ReplayWebhookEventResponse

object string

The type of object.

id string

The ID of the replayed webhook event.

200 Response

{
  "object": "webhook_event",
  "id": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2"
}

Example generated from the schema

Retrieve a list of webhook event attempts

GET /webhooks/{webhook_id}/events/{event_id}/attempts

Path parameters

webhook_id string · uuid

The Webhook ID.

event_id string

The Webhook Event ID.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

Responses

200

ListWebhookEventAttemptsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing webhook event attempt information.

1 field

items object

4 fields

id string

The ID of the webhook event attempt.

http_status_code integer

The HTTP status code returned by the webhook endpoint.

response string

The response body returned by the webhook endpoint.

sent_at string · date-time

Timestamp indicating when the attempt was sent.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "atmpt_1srOrx2ZWZBpBUvZwXKQmoEYga2",
      "http_status_code": 200,
      "response": "{\"ok\":true}",
      "sent_at": "2026-08-22T15:33:12.000Z"
    }
  ]
}

Example generated from the schema

Templates

Create and manage Templates through the Resend API.

Retrieve a list of templates

GET /templates

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListTemplatesResponseSuccess

object string

Type of the response object.

data array of TemplateListItem

Array containing templates information.

1 field

items TemplateListItem

7 fields

id string

The ID of the template.

name string

The name of the template.

status string

The publication status of the template.

enum draftpublished

published_at string

nullable

Timestamp indicating when the template was published.

created_at string

Timestamp indicating when the template was created.

updated_at string

Timestamp indicating when the template was last updated.

alias string

The alias of the template.

has_more boolean

Indicates if there are more templates to retrieve.

200 Response

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "draft",
      "published_at": "2023-10-06 23:47:56.678+00",
      "created_at": "2023-10-06 23:47:56.678+00",
      "updated_at": "2023-10-06 23:47:56.678+00",
      "alias": "string"
    }
  ],
  "has_more": false
}

Example generated from the schema

Create a template

POST /templates

Request body CreateTemplateRequest

name string

The name of the template.

alias string

The alias of the template.

from string

Sender email address. To include a friendly name, use the format "Your Name sender@domain.com".

subject string

Email subject.

reply_to array of string

Reply-to email addresses.

1 field

items string

html string

The HTML version of the template.

text string

The plain text version of the template.

variables array of TemplateVariableInput

1 field

items TemplateVariableInput

3 fields

key string

The key of the variable.

type string

The type of the variable.

enum stringnumberbooleanobjectlist

fallback_value one of

The fallback value of the variable.

5 fields

one of · 1 string

one of · 2 number

one of · 3 boolean

one of · 4 object

one of · 5 array

1 field

items

Responses

201

CreateTemplateResponseSuccess

id string

The ID of the template.

object string

The object type of the response.

POST /templates

{
  "name": "string",
  "alias": "string",
  "from": "string",
  "subject": "string",
  "reply_to": [
    "string"
  ],
  "html": "string",
  "text": "string",
  "variables": [
    {
      "key": "string",
      "type": "string",
      "fallback_value": "string"
    }
  ]
}

Example generated from the schema

201 Response

{
  "id": "string",
  "object": "template"
}

Example generated from the schema

Retrieve a single template

GET /templates/{id}

Path parameters

id string

The Template ID or alias.

Responses

200

Template

object string

The type of object.

id string

The ID of the template.

current_version_id string

The ID of the current version of the template.

name string

The name of the template.

alias string

The alias of the template.

from string

Sender email address. To include a friendly name, use the format "Your Name sender@domain.com".

subject string

Email subject.

reply_to array of string

nullable

Reply-to email addresses.

1 field

items string

html string

The HTML version of the template.

text string

The plain text version of the template.

variables array of TemplateVariable

1 field

items TemplateVariable

6 fields

id string

The ID of the template variable.

key string

The key of the variable.

type string

The type of the variable.

enum stringnumberbooleanobjectlist

fallback_value one of

The fallback value of the variable.

5 fields

one of · 1 string

one of · 2 number

one of · 3 boolean

one of · 4 object

one of · 5 array

1 field

items

created_at string

Timestamp indicating when the variable was created.

updated_at string

Timestamp indicating when the variable was last updated.

created_at string

Timestamp indicating when the template was created.

updated_at string

Timestamp indicating when the template was last updated.

status string

The publication status of the template.

enum draftpublished

published_at string

nullable

Timestamp indicating when the template was published.

has_unpublished_versions boolean

Indicates whether the template has unpublished versions.

200 Response

{
  "object": "template",
  "id": "string",
  "current_version_id": "string",
  "name": "string",
  "alias": "string",
  "from": "string",
  "subject": "string",
  "reply_to": [
    "string"
  ],
  "html": "string",
  "text": "string",
  "variables": [
    {
      "id": "string",
      "key": "string",
      "type": "string",
      "fallback_value": "string",
      "created_at": "2023-10-06 23:47:56.678+00",
      "updated_at": "2023-10-06 23:47:56.678+00"
    }
  ],
  "created_at": "2023-10-06 23:47:56.678+00",
  "updated_at": "2023-10-06 23:47:56.678+00",
  "status": "draft",
  "published_at": "2023-10-06 23:47:56.678+00",
  "has_unpublished_versions": false
}

Example generated from the schema

Update an existing template

PATCH /templates/{id}

Path parameters

id string

The Template ID or alias.

Request body UpdateTemplateOptions

name string

The name of the template.

alias string

The alias of the template.

from string

Sender email address. To include a friendly name, use the format "Your Name sender@domain.com".

subject string

Email subject.

reply_to array of string

Reply-to email addresses.

1 field

items string

html string

The HTML version of the template.

text string

The plain text version of the template.

variables array of TemplateVariableInput

1 field

items TemplateVariableInput

3 fields

key string

The key of the variable.

type string

The type of the variable.

enum stringnumberbooleanobjectlist

fallback_value one of

The fallback value of the variable.

5 fields

one of · 1 string

one of · 2 number

one of · 3 boolean

one of · 4 object

one of · 5 array

1 field

items

Responses

200

UpdateTemplateResponseSuccess

id string

The ID of the template.

object string

The object type of the response.

PATCH /templates/{id}

{
  "name": "string",
  "alias": "string",
  "from": "string",
  "subject": "string",
  "reply_to": [
    "string"
  ],
  "html": "string",
  "text": "string",
  "variables": [
    {
      "key": "string",
      "type": "string",
      "fallback_value": "string"
    }
  ]
}

Example generated from the schema

200 Response

{
  "id": "string",
  "object": "template"
}

Example generated from the schema

Remove an existing template

DELETE /templates/{id}

Path parameters

id string

The Template ID or alias.

Responses

200

RemoveTemplateResponseSuccess

object string

Type of the response object.

id string

The ID of the template.

deleted boolean

Indicates whether the template was successfully deleted.

200 Response

{
  "object": "template",
  "id": "string",
  "deleted": true
}

Example generated from the schema

Publish a template

POST /templates/{id}/publish

Path parameters

id string

The Template ID or alias.

Responses

200

PublishTemplateResponseSuccess

id string

The ID of the template.

object string

The object type of the response.

200 Response

{
  "id": "string",
  "object": "template"
}

Example generated from the schema

Duplicate a template

POST /templates/{id}/duplicate

Path parameters

id string

The Template ID or alias.

Responses

200

DuplicateTemplateResponseSuccess

id string

The ID of the duplicated template.

object string

The object type of the response.

200 Response

{
  "id": "string",
  "object": "template"
}

Example generated from the schema

Broadcasts

Create and manage Broadcasts through the Resend API.

Retrieve a list of broadcasts

GET /broadcasts

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListBroadcastsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing broadcast information.

1 field

items object

9 fields

id string

Unique identifier for the broadcast.

name string

Name of the broadcast.

audience_id string

deprecated

Deprecated. Use segment_id instead.

segment_id string

Unique identifier of the segment this broadcast will be sent to.

status string

The status of the broadcast.

created_at string

Timestamp indicating when the broadcast was created.

scheduled_at string

Timestamp indicating when the broadcast is scheduled to be sent.

sent_at string

Timestamp indicating when the broadcast was sent.

topic_id string

The topic ID that the broadcast is scoped to.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "name": "November announcements",
      "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "status": "draft",
      "created_at": "2023-10-06 22:59:55.977+00",
      "scheduled_at": "2023-10-06 22:59:55.977+00",
      "sent_at": "2023-10-06 22:59:55.977+00",
      "topic_id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e"
    }
  ]
}

Example generated from the schema

Create a broadcast

POST /broadcasts

Request body CreateBroadcastOptions

name string

Name of the broadcast.

segment_id string

Unique identifier of the segment this broadcast will be sent to.

audience_id string

deprecated

Use segment_id instead. Unique identifier of the segment this broadcast will be sent to.

from string

The email address of the sender.

subject string

The subject line of the email.

reply_to array of string

The email addresses to which replies should be sent.

1 field

items string

preview_text string

The preview text of the email.

html string

The HTML version of the message.

text string

The plain text version of the message.

topic_id string

The topic ID that the broadcast will be scoped to.

send boolean

Whether to send the broadcast immediately or keep it as a draft.

scheduled_at string

Schedule time to send the broadcast. Can only be used if send is true.

Responses

201

CreateBroadcastResponseSuccess

id string

The ID of the broadcast.

object string

The object type of the response.

POST /broadcasts

{
  "name": "string",
  "segment_id": "string",
  "audience_id": "string",
  "from": "string",
  "subject": "string",
  "reply_to": [
    "string"
  ],
  "preview_text": "Here are our announcements",
  "html": "string",
  "text": "string",
  "topic_id": "string",
  "send": false,
  "scheduled_at": "string"
}

Example generated from the schema

201 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "broadcast"
}

Example generated from the schema

Retrieve a single broadcast

GET /broadcasts/{id}

Path parameters

id string

The Broadcast ID.

Responses

200

GetBroadcastResponseSuccess

id string

Unique identifier for the broadcast.

name string

Name of the broadcast.

audience_id string

deprecated nullable

Deprecated: use segment_id instead. Unique identifier of the segment this broadcast will be sent to.

segment_id string

nullable

Unique identifier of the segment this broadcast will be sent to.

from string

The email address of the sender.

subject string

The subject line of the email.

reply_to array of string

The email addresses to which replies should be sent.

1 field

items string

preview_text string

The preview text of the email.

status string

The status of the broadcast.

created_at string

Timestamp indicating when the broadcast was created.

scheduled_at string

Timestamp indicating when the broadcast is scheduled to be sent.

sent_at string

Timestamp indicating when the broadcast was sent.

text string

nullable

The plain text version of the broadcast content.

html string

nullable

The HTML version of the broadcast content.

topic_id string

nullable

The topic ID that the broadcast is scoped to.

200 Response

{
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "name": "November announcements",
  "audience_id": "string",
  "segment_id": "string",
  "from": "Acme <onboarding@resend.dev>",
  "subject": "Hello World",
  "reply_to": [
    "string"
  ],
  "preview_text": "Here are our announcements",
  "status": "draft",
  "created_at": "2023-10-06 22:59:55.977+00",
  "scheduled_at": "2023-10-06 22:59:55.977+00",
  "sent_at": "2023-10-06 22:59:55.977+00",
  "text": "Hello {{{FIRST_NAME|there}}}!",
  "html": "<p>Hello {{{FIRST_NAME|there}}}!</p>",
  "topic_id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e"
}

Example generated from the schema

Update an existing broadcast

PATCH /broadcasts/{id}

Path parameters

id string

The Broadcast ID.

Request body UpdateBroadcastOptions

name string

Name of the broadcast.

audience_id string

deprecated

Use segment_id instead. Unique identifier of the audience this broadcast will be sent to.

segment_id string

Unique identifier of the segment this broadcast will be sent to.

from string

The email address of the sender.

subject string

The subject line of the email.

reply_to array of string

The email addresses to which replies should be sent.

1 field

items string

preview_text string

The preview text of the email.

html string

The HTML version of the message.

text string

The plain text version of the message.

topic_id string

The topic ID that the broadcast will be scoped to.

Responses

200

UpdateBroadcastResponseSuccess

id string

The ID of the broadcast.

object string

The object type of the response.

PATCH /broadcasts/{id}

{
  "name": "string",
  "audience_id": "string",
  "segment_id": "string",
  "from": "string",
  "subject": "string",
  "reply_to": [
    "string"
  ],
  "preview_text": "string",
  "html": "string",
  "text": "string",
  "topic_id": "string"
}

Example generated from the schema

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "broadcast"
}

Example generated from the schema

Remove an existing broadcast that is in the draft status

DELETE /broadcasts/{id}

Path parameters

id string

The Broadcast ID.

Responses

200

RemoveBroadcastResponseSuccess

id string

The ID of the broadcast.

object string

Type of the response object.

deleted boolean

The deleted attribute indicates that the corresponding broadcast has been deleted.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "broadcast",
  "deleted": true
}

Example generated from the schema

Send or schedule a broadcast

POST /broadcasts/{id}/send

Path parameters

id string

The Broadcast ID.

Request body SendBroadcastOptions

scheduled_at string

Schedule email to be sent later. The date should be in ISO 8601 format.

Responses

200

SendBroadcastResponseSuccess

id string

The ID of the broadcast.

POST /broadcasts/{id}/send

{
  "scheduled_at": "string"
}

Example generated from the schema

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
}

Example generated from the schema

Cancel a broadcast

POST /broadcasts/{id}/cancel

Cancels a broadcast that is queued or scheduled. Canceling a queued broadcast stops it mid-send; emails already sent are not affected, but no further emails will go out.

Path parameters

id string · uuid

The Broadcast ID.

Responses

200

CancelBroadcastResponseSuccess

id string

The ID of the broadcast.

object string

The object type of the response.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "broadcast"
}

Example generated from the schema

Duplicate a broadcast

POST /broadcasts/{id}/duplicate

Creates a new draft broadcast with the same segment, topic, sender, subject, reply-to, preview text, and content as the source. The copy is named after the source with " (copy)" appended, truncated to 70 characters.

Path parameters

id string · uuid

The Broadcast ID.

Responses

201

Created

DuplicateBroadcastResponseSuccess

id string

The ID of the duplicated broadcast.

object string

The object type of the response.

201 Response

{
  "id": "1f85ae38-f5b9-4c1f-8766-667a53970fea",
  "object": "broadcast"
}

Example generated from the schema

Retrieve broadcast recipients

GET /broadcasts/{id}/recipients

Retrieve the recipients of a broadcast for a given event type, such as who opened, clicked, or bounced.

Path parameters

id string · uuid

The Broadcast ID.

Query parameters

type string

The recipient event type to filter by.

enum sentdeliveredopenedclickedbouncedcomplainedunsubscribedsuppressed

email string

Filter recipients whose email address contains this value.

bounce_type string

Filter bounced recipients by bounce type. Only valid when type is bounced.

enum permanenttransientundetermined

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListBroadcastRecipientsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing broadcast recipients.

1 field

items object

6 fields

id string

Opaque cursor identifying this row, used for pagination.

contact_id string

nullable

The ID of the contact associated with this recipient, if one exists.

email string

The recipient's email address.

count integer

The number of times this recipient triggered the event. Only present when type is opened or clicked.

bounce_type string

The type of bounce. Only present when type is bounced.

enum permanenttransientundetermined

clicked_links array of object

The links this recipient clicked. Only present when type is clicked.

1 field

items object

2 fields

url string

The clicked URL.

clicks integer

The number of times this recipient clicked this URL.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "b2Zmc2V0OjA",
      "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "steve.wozniak@gmail.com",
      "count": 3,
      "bounce_type": "permanent",
      "clicked_links": [
        {
          "url": "https://resend.com/pricing",
          "clicks": 2
        }
      ]
    }
  ]
}

Example generated from the schema

Retrieve a broadcast's clicked links

GET /broadcasts/{id}/clicked-links

Path parameters

id string · uuid

The Broadcast ID.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListBroadcastClickedLinksResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing the broadcast's clicked links.

1 field

items object

4 fields

id string

An opaque cursor for this row, used only for pagination. It does not identify any entity in Resend.

url string

The URL that was clicked.

clicks integer

Total number of clicks on this URL.

unique_clicks integer

Number of unique clicks on this URL.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "b2Zmc2V0OjA",
      "url": "https://resend.com/pricing",
      "clicks": 42,
      "unique_clicks": 30
    }
  ]
}

Example generated from the schema

Segments

Create and manage Segments through the Resend API.

Retrieve a list of segments

GET /segments

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListSegmentsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing segment information.

1 field

items object

4 fields

id string

Unique identifier for the segment.

name string

Name of the segment.

audience_id string

deprecated

The ID of the audience this segment belongs to.

created_at string

Timestamp indicating when the segment was created.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "name": "string",
      "audience_id": "string",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create a new segment

POST /segments

Request body CreateSegmentOptions

name string

The name of the segment.

audience_id string

deprecated

The ID of the audience this segment belongs to.

filter object

Filter conditions for the segment.

Responses

201

CreateSegmentResponseSuccess

id string

The ID of the segment.

object string

The object type of the response.

POST /segments

{
  "name": "string",
  "audience_id": "string",
  "filter": {}
}

Example generated from the schema

201 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "segment"
}

Example generated from the schema

Retrieve a single segment

GET /segments/{id}

Path parameters

id string

The Segment ID.

Responses

200

GetSegmentResponseSuccess

id string

The ID of the segment.

object string

The object type.

name string

The name of the segment.

audience_id string

deprecated

The ID of the audience this segment belongs to.

filter object

Filter conditions for the segment.

created_at string

Timestamp indicating when the segment was created.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "segment",
  "name": "Active Users",
  "audience_id": "string",
  "filter": {},
  "created_at": "2023-10-06 23:47:56.678+00"
}

Example generated from the schema

Update an existing segment

PATCH /segments/{id}

Path parameters

id string

The Segment ID.

Request body UpdateSegmentOptions

name string

The name of the segment.

Responses

200

UpdateSegmentResponseSuccess

id string

The ID of the segment.

object string

The object type.

PATCH /segments/{id}

{
  "name": "string"
}

Example generated from the schema

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "segment"
}

Example generated from the schema

Remove an existing segment

DELETE /segments/{id}

Path parameters

id string

The Segment ID.

Responses

200

RemoveSegmentResponseSuccess

id string

The ID of the segment.

object string

The object type.

deleted boolean

Indicates whether the segment was successfully deleted.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "segment",
  "deleted": true
}

Example generated from the schema

Retrieve a list of contacts in a segment

GET /segments/{id}/contacts

Path parameters

id string · uuid

The Segment ID.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListContactsResponseSuccessused by 2 operations

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing contact information.

1 field

items object

6 fields

id string

Unique identifier for the contact.

email string

Email address of the contact.

first_name string

nullable

First name of the contact.

last_name string

nullable

Last name of the contact.

created_at string

Timestamp indicating when the contact was created.

unsubscribed boolean

Indicates if the contact is unsubscribed.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "steve.wozniak@gmail.com",
      "first_name": "Steve",
      "last_name": "Wozniak",
      "created_at": "2023-10-06 23:47:56.678+00",
      "unsubscribed": false
    }
  ]
}

Example generated from the schema

Topics

Create and manage Topics through the Resend API.

Retrieve a list of topics

GET /topics

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListTopicsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing topic information.

1 field

items object

6 fields

id string

Unique identifier for the topic.

name string

Name of the topic.

description string

A description of the topic.

default_subscription string

The default subscription status for the topic.

enum opt_inopt_out

visibility string

The visibility of the topic.

enum publicprivate

created_at string

Timestamp indicating when the topic was created.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "default_subscription": "opt_in",
      "visibility": "public",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create a new topic

POST /topics

Request body CreateTopicOptions

name string

The name of the topic. Max 50 characters.

rules max length 50

default_subscription string

The default subscription status for the topic. Cannot be changed after creation.

enum opt_inopt_out

description string

A description of the topic. Max 200 characters.

rules max length 200

visibility string

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.

enum publicprivate

default private

Responses

201

CreateTopicResponseSuccess

id string

The ID of the topic.

object string

The object type of the response.

POST /topics

{
  "name": "string",
  "default_subscription": "opt_in",
  "description": "string",
  "visibility": "private"
}

Example generated from the schema

201 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "topic"
}

Example generated from the schema

Retrieve a single topic

GET /topics/{id}

Path parameters

id string

The Topic ID.

Responses

200

GetTopicResponseSuccess

id string

The ID of the topic.

object string

The object type.

name string

The name of the topic.

description string

A description of the topic.

default_subscription string

The default subscription status for the topic.

enum opt_inopt_out

visibility string

The visibility of the topic.

enum publicprivate

created_at string

Timestamp indicating when the topic was created.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "topic",
  "name": "Newsletter",
  "description": "string",
  "default_subscription": "opt_in",
  "visibility": "public",
  "created_at": "2023-10-06 23:47:56.678+00"
}

Example generated from the schema

Update an existing topic

PATCH /topics/{id}

Path parameters

id string

The Topic ID.

Request body UpdateTopicOptions

name string

The name of the topic. Max 50 characters.

rules max length 50

description string

A description of the topic. Max 200 characters.

rules max length 200

visibility string

The visibility of the topic.

enum publicprivate

Responses

200

UpdateTopicResponseSuccess

id string

The ID of the topic.

object string

The object type.

PATCH /topics/{id}

{
  "name": "string",
  "description": "string",
  "visibility": "public"
}

Example generated from the schema

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "topic"
}

Example generated from the schema

Remove an existing topic

DELETE /topics/{id}

Path parameters

id string

The Topic ID.

Responses

200

RemoveTopicResponseSuccess

id string

The ID of the topic.

object string

The object type.

deleted boolean

Indicates whether the topic was successfully deleted.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "topic",
  "deleted": true
}

Example generated from the schema

Contact Properties

Create and manage Contact Properties through the Resend API.

Retrieve a list of contact properties

GET /contact-properties

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListContactPropertiesResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing contact property information.

1 field

items object

5 fields

id string

Unique identifier for the contact property.

key string

The property key.

type string

The property type.

fallback_value one of

The default value when the property is not set for a contact.

2 fields

one of · 1 string

one of · 2 number

created_at string

Timestamp indicating when the contact property was created.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "key": "string",
      "type": "string",
      "fallback_value": "string",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create a new contact property

POST /contact-properties

Request body CreateContactPropertyOptions

key string

The property key. Max length is 50 characters. Only alphanumeric characters and underscores are allowed.

type string

The property type.

enum stringnumber

fallback_value one of

The default value to use when the property is not set for a contact. Must match the type specified in the type field.

2 fields

one of · 1 string

one of · 2 number

Responses

201

CreateContactPropertyResponseSuccess

id string

The ID of the contact property.

object string

The object type of the response.

POST /contact-properties

{
  "key": "string",
  "type": "string",
  "fallback_value": "string"
}

Example generated from the schema

201 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "contact_property"
}

Example generated from the schema

Retrieve a single contact property

GET /contact-properties/{id}

Path parameters

id string

The Contact Property ID.

Responses

200

GetContactPropertyResponseSuccess

object string

The object type.

id string

The ID of the contact property.

key string

The property key.

type string

The property type.

fallback_value one of

The default value when the property is not set for a contact.

2 fields

one of · 1 string

one of · 2 number

created_at string

Timestamp indicating when the contact property was created.

200 Response

{
  "object": "contact_property",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "key": "company_name",
  "type": "string",
  "fallback_value": "Acme Corp",
  "created_at": "2023-10-06 23:47:56.678+00"
}

Example generated from the schema

Update an existing contact property

PATCH /contact-properties/{id}

Path parameters

id string

The Contact Property ID.

Request body UpdateContactPropertyOptions

fallback_value one of

The default value to use when the property is not set for a contact. Must match the type of the property.

2 fields

one of · 1 string

one of · 2 number

Responses

200

UpdateContactPropertyResponseSuccess

id string

The ID of the contact property.

object string

The object type.

PATCH /contact-properties/{id}

{
  "fallback_value": "string"
}

Example generated from the schema

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "contact_property"
}

Example generated from the schema

Remove an existing contact property

DELETE /contact-properties/{id}

Path parameters

id string

The Contact Property ID.

Responses

200

RemoveContactPropertyResponseSuccess

id string

The ID of the contact property.

object string

The object type.

deleted boolean

Indicates whether the contact property was successfully deleted.

200 Response

{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "object": "contact_property",
  "deleted": true
}

Example generated from the schema

Suppressions

Create and manage Suppressions through the Resend API.

Retrieve a list of suppressions

GET /suppressions

Query parameters

origin string

Filter suppressions by origin.

enum bouncecomplaintmanual

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListSuppressionsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing suppression information.

1 field

items object

5 fields

id string

Unique identifier for the suppression.

email string

Email address that is suppressed.

origin string

Origin of the suppression.

enum bouncecomplaintmanual

source_id string

nullable

Identifier of the event that caused the suppression, such as the email that bounced or complained.

created_at string

Timestamp indicating when the suppression was created.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "steve.wozniak@gmail.com",
      "origin": "manual",
      "source_id": "479e3145-dd38-476b-932c-529ceb705947",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create a suppression

POST /suppressions

Request body CreateSuppressionOptions

email string

Email address to suppress.

Responses

201

CreateSuppressionResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the created suppression.

POST /suppressions

{
  "email": "steve.wozniak@gmail.com"
}

Example generated from the schema

201 Response

{
  "object": "suppression",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3"
}

Example generated from the schema

Add up to 100 suppressions at once

POST /suppressions/batch/add

Request body BatchAddSuppressionsOptions

emails array of string

Email addresses to suppress.

rules min items 1max items 100

1 field

items string

Responses

201

BatchAddSuppressionsResponseSuccess

data array of object

Array containing the created suppressions.

1 field

items object

2 fields

object string

Type of the object.

id string

Unique identifier for the suppression.

POST /suppressions/batch/add

{
  "emails": [
    "steve.wozniak@gmail.com"
  ]
}

Example generated from the schema

201 Response

{
  "data": [
    {
      "object": "suppression",
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3"
    }
  ]
}

Example generated from the schema

Remove up to 100 suppressions at once

POST /suppressions/batch/remove

Request body BatchRemoveSuppressionsOptions

Provide either emails or ids, but not both.

emails array of string

Email addresses to remove from the suppression list.

rules min items 1max items 100

1 field

items string

ids array of string

Suppression IDs to remove from the suppression list.

rules min items 1max items 100

1 field

items string

Responses

200

BatchRemoveSuppressionsResponseSuccess

data array of object

Array containing the removed suppressions.

1 field

items object

3 fields

object string

Type of the object.

id string

Unique identifier for the suppression.

deleted boolean

Indicates whether the suppression was successfully deleted.

POST /suppressions/batch/remove

{
  "emails": [
    "steve.wozniak@gmail.com"
  ],
  "ids": [
    "e169aa45-1ecf-4183-9955-b1499d5701d3"
  ]
}

Example generated from the schema

200 Response

{
  "data": [
    {
      "object": "suppression",
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "deleted": true
    }
  ]
}

Example generated from the schema

Retrieve a single suppression by ID or email

GET /suppressions/{suppression}

Path parameters

suppression string

The Suppression ID or email address.

Responses

200

GetSuppressionResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the suppression.

email string

Email address that is suppressed.

origin string

Origin of the suppression.

enum bouncecomplaintmanual

source_id string

nullable

Identifier of the event that caused the suppression, such as the email that bounced or complained.

created_at string

Timestamp indicating when the suppression was created.

200 Response

{
  "object": "suppression",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "steve.wozniak@gmail.com",
  "origin": "manual",
  "source_id": "479e3145-dd38-476b-932c-529ceb705947",
  "created_at": "2023-10-06 23:47:56.678+00"
}

Example generated from the schema

Remove a single suppression by ID or email

DELETE /suppressions/{suppression}

Path parameters

suppression string

The Suppression ID or email address.

Responses

200

RemoveSuppressionResponseSuccess

object string

Type of the response object.

id string

Unique identifier for the removed suppression.

deleted boolean

Indicates whether the suppression was successfully deleted.

200 Response

{
  "object": "suppression",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "deleted": true
}

Example generated from the schema

Logs

Retrieve API request logs through the Resend API.

Retrieve a list of logs

GET /logs

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListLogsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of LogSummary

Array containing log information.

1 field

items LogSummary

6 fields

id string · uuid

The log ID.

created_at string

The date the log was created.

endpoint string

The API endpoint that was called.

method string

The HTTP method used.

enum GETPOSTPUTDELETEPATCHOPTIONS

response_status integer

The HTTP status code of the response.

user_agent string

nullable

The user agent of the request.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2023-10-06 23:47:56.678+00",
      "endpoint": "string",
      "method": "GET",
      "response_status": 0,
      "user_agent": "string"
    }
  ]
}

Example generated from the schema

Retrieve a single log

GET /logs/{log_id}

Path parameters

log_id string · uuid

The ID of the log.

Responses

200

Log

object string

Type of the response object.

id string · uuid

The log ID.

created_at string

The date the log was created.

endpoint string

The API endpoint that was called.

method string

The HTTP method used.

enum GETPOSTPUTDELETEPATCHOPTIONS

response_status integer

The HTTP status code of the response.

user_agent string

nullable

The user agent of the request.

request_body object

nullable

The request body sent to the API.

response_body object

nullable

The response body returned by the API.

200 Response

{
  "object": "log",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-10-06 23:47:56.678+00",
  "endpoint": "string",
  "method": "GET",
  "response_status": 0,
  "user_agent": "string",
  "request_body": {},
  "response_body": {}
}

Example generated from the schema

Automations

Create and manage Automations through the Resend API.

Retrieve a list of automations

GET /automations

Query parameters

status string

Filter automations by status.

enum enableddisabled

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListAutomationsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of AutomationListItem

Array of automations.

1 field

items AutomationListItem

5 fields

id string

The ID of the automation.

name string

The name of the automation.

status string

The current status of the automation.

enum enableddisabled

created_at string

The date and time the automation was created.

updated_at string

The date and time the automation was last updated.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "enabled",
      "created_at": "2023-10-06 23:47:56.678+00",
      "updated_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create an automation

POST /automations

Request body CreateAutomationRequest

name string

The name of the automation.

rules min length 1

status string

The initial status of the automation. Defaults to disabled.

enum enableddisabled

default disabled

steps array of AutomationStep

The steps that compose the automation workflow. Must include at least one trigger step.

rules min items 1max items 150

1 field

items AutomationStep

A step in an automation workflow. The config object varies based on the step type.

3 fields

key string

A unique key for this step within the automation graph.

type string

The type of automation step.

enum triggersend_emaildelaywait_for_eventconditioncontact_updatecontact_deleteadd_to_segment

config object

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 }

connections array of AutomationConnection

The connections between steps in the automation graph.

1 field

items AutomationConnection

A connection between two steps in the automation graph.

3 fields

from string

The key of the source step.

to string

The key of the target step.

type string

The type of connection. Defaults to default.

enum defaultcondition_metcondition_not_mettimeoutevent_received

default default

Responses

201

CreateAutomationResponse

object string

Type of the response object.

id string

The ID of the created automation.

POST /automations

{
  "name": "x",
  "status": "disabled",
  "steps": [
    {
      "key": "string",
      "type": "trigger",
      "config": {}
    }
  ],
  "connections": [
    {
      "from": "string",
      "to": "string",
      "type": "default"
    }
  ]
}

Example generated from the schema

201 Response

{
  "object": "automation",
  "id": "string"
}

Example generated from the schema

Retrieve a single automation

GET /automations/{automation_id}

Path parameters

automation_id string · uuid

The ID of the automation.

Responses

200

Automation

object string

Type of the response object.

id string

The ID of the automation.

name string

The name of the automation.

status string

The current status of the automation.

enum enableddisabled

created_at string

The date and time the automation was created.

updated_at string

The date and time the automation was last updated.

steps array of AutomationStepResponse

The steps in the active version of the automation.

1 field

items AutomationStepResponse

A step as returned when retrieving an automation.

3 fields

key string

The unique key of this step within the automation graph.

type string

The type of automation step.

enum triggersend_emaildelaywait_for_eventconditioncontact_updatecontact_deleteadd_to_segment

config object

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.

connections array of AutomationConnection

The connections between steps in the active version of the automation.

1 field

items AutomationConnection

A connection between two steps in the automation graph.

3 fields

from string

The key of the source step.

to string

The key of the target step.

type string

The type of connection. Defaults to default.

enum defaultcondition_metcondition_not_mettimeoutevent_received

default default

200 Response

{
  "object": "automation",
  "id": "string",
  "name": "string",
  "status": "enabled",
  "created_at": "2023-10-06 23:47:56.678+00",
  "updated_at": "2023-10-06 23:47:56.678+00",
  "steps": [
    {
      "key": "string",
      "type": "trigger",
      "config": {}
    }
  ],
  "connections": [
    {
      "from": "string",
      "to": "string",
      "type": "default"
    }
  ]
}

Example generated from the schema

Update an automation

PATCH /automations/{automation_id}

Path parameters

automation_id string · uuid

The ID of the automation.

Request body PatchAutomationRequest

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.

name string

The name of the automation.

rules min length 1

status string

The status of the automation.

enum enableddisabled

steps array of AutomationStep

The steps that compose the automation workflow. Must be provided together with connections.

rules min items 1max items 150

1 field

items AutomationStep

A step in an automation workflow. The config object varies based on the step type.

3 fields

key string

A unique key for this step within the automation graph.

type string

The type of automation step.

enum triggersend_emaildelaywait_for_eventconditioncontact_updatecontact_deleteadd_to_segment

config object

connections array of AutomationConnection

The connections between steps in the automation graph. Must be provided together with steps.

1 field

items AutomationConnection

A connection between two steps in the automation graph.

3 fields

from string

The key of the source step.

to string

The key of the target step.

type string

The type of connection. Defaults to default.

enum defaultcondition_metcondition_not_mettimeoutevent_received

default default

Responses

200

PatchAutomationResponse

object string

Type of the response object.

id string

The ID of the updated automation.

PATCH /automations/{automation_id}

{
  "name": "x",
  "status": "enabled",
  "steps": [
    {
      "key": "string",
      "type": "trigger",
      "config": {}
    }
  ],
  "connections": [
    {
      "from": "string",
      "to": "string",
      "type": "default"
    }
  ]
}

Example generated from the schema

200 Response

{
  "object": "automation",
  "id": "string"
}

Example generated from the schema

Delete an automation

DELETE /automations/{automation_id}

Path parameters

automation_id string · uuid

The ID of the automation.

Responses

200

DeleteAutomationResponse

object string

Type of the response object.

id string

The ID of the deleted automation.

deleted boolean

Indicates whether the automation was successfully deleted.

200 Response

{
  "object": "automation",
  "id": "string",
  "deleted": true
}

Example generated from the schema

Duplicate an automation

POST /automations/{automation_id}/duplicate

Path parameters

automation_id string · uuid

The ID of the automation.

Responses

201

DuplicateAutomationResponse

object string

Type of the response object.

id string

The ID of the duplicated automation.

201 Response

{
  "object": "automation",
  "id": "string"
}

Example generated from the schema

Stop an automation

POST /automations/{automation_id}/stop

Path parameters

automation_id string · uuid

The ID of the automation.

Responses

200

StopAutomationResponse

object string

Type of the response object.

id string

The ID of the stopped automation.

status string

The status of the automation after stopping.

200 Response

{
  "object": "automation",
  "id": "string",
  "status": "disabled"
}

Example generated from the schema

Retrieve a list of automation runs

GET /automations/{automation_id}/runs

Path parameters

automation_id string · uuid

The ID of the automation.

Query parameters

status string

Filter runs by status. Comma-separated list of: running, completed, failed, cancelled.

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListAutomationRunsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of AutomationRunListItem

Array of automation runs.

1 field

items AutomationRunListItem

5 fields

id string

The ID of the automation run.

status string

The current status of the automation run.

enum runningcompletedfailedcancelled

started_at string

nullable

The date and time the run started.

completed_at string

nullable

The date and time the run completed.

created_at string

The date and time the run was created.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "status": "running",
      "started_at": "2023-10-06 23:47:56.678+00",
      "completed_at": "2023-10-06 23:47:56.678+00",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Retrieve a single automation run

GET /automations/{automation_id}/runs/{run_id}

Path parameters

automation_id string · uuid

The ID of the automation.

run_id string · uuid

The ID of the automation run.

Responses

200

AutomationRun

object string

Type of the response object.

id string

The ID of the automation run.

status string

The current status of the automation run.

enum runningcompletedfailedcancelled

started_at string

nullable

The date and time the run started.

completed_at string

nullable

The date and time the run completed.

created_at string

The date and time the run was created.

steps array of AutomationRunStep

The steps executed in this run, sorted in graph order.

1 field

items AutomationRunStep

A step execution within an automation run.

8 fields

key string

The key of the automation step.

type string

The type of automation step.

enum triggersend_emaildelaywait_for_eventconditioncontact_updatecontact_deleteadd_to_segment

status string

The execution status of this step.

started_at string

nullable

The date and time the step started executing.

completed_at string

nullable

The date and time the step completed executing.

output object

nullable

The output produced by the step, if any.

error object

nullable

The error produced by the step, if any.

created_at string

The date and time the step record was created.

200 Response

{
  "object": "automation_run",
  "id": "string",
  "status": "running",
  "started_at": "2023-10-06 23:47:56.678+00",
  "completed_at": "2023-10-06 23:47:56.678+00",
  "created_at": "2023-10-06 23:47:56.678+00",
  "steps": [
    {
      "key": "string",
      "type": "trigger",
      "status": "string",
      "started_at": "2023-10-06 23:47:56.678+00",
      "completed_at": "2023-10-06 23:47:56.678+00",
      "output": {},
      "error": {},
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Events

Create and manage Events through the Resend API.

Retrieve a list of events

GET /events

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListEventsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of EventSummary

Array containing event information.

1 field

items EventSummary

5 fields

id string · uuid

The event ID.

name string

The event name.

schema object

nullable

A flat key/type map defining the event payload schema. Supported types are string, number, boolean, and date.

created_at string

The date and time the event was created.

updated_at string

nullable

The date and time the event was last updated.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "schema": {},
      "created_at": "2023-10-06 23:47:56.678+00",
      "updated_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Example generated from the schema

Create an event

POST /events

Request body CreateEventRequest

name string

The name of the event. Cannot start with the reserved resend: prefix.

schema object

nullable

An optional flat key/type map defining the event payload schema. Supported types are string, number, boolean, and date.

Responses

201

CreateEventResponse

object string

Type of the response object.

id string · uuid

The ID of the created event.

POST /events

{
  "name": "string",
  "schema": {}
}

Example generated from the schema

201 Response

{
  "object": "event",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Example generated from the schema

Send an event

POST /events/send

Request body SendEventRequest

event string

The name of the event to send.

contact_id string · uuid

The ID of the contact to associate with this event. Exactly one of contact_id or email must be provided.

email string · email

The email address to associate with this event. Exactly one of contact_id or email must be provided.

payload object

An optional payload of key/value pairs to include with the event.

Responses

202

Accepted

SendEventResponse

object string

Type of the response object.

event string

The name of the event that was sent.

POST /events/send

{
  "event": "string",
  "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "payload": {}
}

Example generated from the schema

202 Response

{
  "object": "event",
  "event": "string"
}

Example generated from the schema

Retrieve a single event

GET /events/{identifier}

Path parameters

identifier string

The event ID (UUID) or event name.

Responses

200

Event

object string

Type of the response object.

id string · uuid

The event ID.

name string

The event name.

schema object

nullable

A flat key/type map defining the event payload schema. Supported types are string, number, boolean, and date.

created_at string

The date and time the event was created.

updated_at string

nullable

The date and time the event was last updated.

200 Response

{
  "object": "event",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "schema": {},
  "created_at": "2023-10-06 23:47:56.678+00",
  "updated_at": "2023-10-06 23:47:56.678+00"
}

Example generated from the schema

Update an event

PATCH /events/{identifier}

Path parameters

identifier string

The event ID (UUID) or event name.

Request body UpdateEventRequest

schema object

nullable

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.

Responses

200

UpdateEventResponse

object string

Type of the response object.

id string · uuid

The ID of the updated event.

PATCH /events/{identifier}

{
  "schema": {}
}

Example generated from the schema

200 Response

{
  "object": "event",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Example generated from the schema

Delete an event

DELETE /events/{identifier}

Path parameters

identifier string

The event ID (UUID) or event name.

Responses

200

RemoveEventResponse

object string

Type of the response object.

id string · uuid

The ID of the deleted event.

deleted boolean

Indicates whether the event was deleted.

200 Response

{
  "object": "event",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deleted": true
}

Example generated from the schema

OAuth

List and manage OAuth grants through the Resend API.

Retrieve a list of OAuth grants

GET /oauth/grants

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListOAuthGrantsResponse

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of OAuthGrant

1 field

items OAuthGrant

7 fields

id string

The ID of the OAuth grant.

client_id string

The ID of the OAuth client the grant was issued to.

scopes array of string

The scopes granted to the OAuth client.

1 field

items string

created_at string

The date and time the OAuth grant was created.

revoked_at string

nullable

The date and time the OAuth grant was revoked, or null if it is still active.

revoked_reason string

nullable

The reason the OAuth grant was revoked, or null if it is still active.

client object

The OAuth client the grant was issued to.

2 fields

name string

The name of the OAuth client.

logo_uri string

nullable

The URL of the OAuth client's logo.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "string",
      "client_id": "string",
      "scopes": [
        "string"
      ],
      "created_at": "2023-10-06 23:47:56.678+00",
      "revoked_at": "2023-10-06 23:47:56.678+00",
      "revoked_reason": "string",
      "client": {
        "name": "string",
        "logo_uri": "string"
      }
    }
  ]
}

Example generated from the schema

Revoke an OAuth grant

DELETE /oauth/grants/{oauth_grant_id}

Path parameters

oauth_grant_id string

The OAuth grant ID.

Responses

200

RevokeOAuthGrantResponse

object string

The type of object.

id string

The ID of the OAuth grant.

revoked_at string · date-time

The date and time the OAuth grant was revoked.

revoked_reason string

The reason the OAuth grant was revoked.

200 Response

{
  "object": "oauth_grant",
  "id": "string",
  "revoked_at": "2023-10-06T23:47:56.678Z",
  "revoked_reason": "string"
}

Example generated from the schema

Usage

Retrieve your account usage and plan limits through the Resend API.

Retrieve account usage

GET /usage

Retrieve your account's current usage and plan limits.

Responses

200

GetUsageResponseSuccess

object string

The type of object.

emails object

2 fields

daily object

5 fields

used integer

Emails sent and received in the current day.

limit integer

nullable

The daily plan limit, or null when the account has a monthly sending subscription.

sent integer

Emails sent today.

received integer

Emails received today.

resets_at string

When the daily counter resets, as an ISO 8601 datetime.

monthly object

5 fields

used integer

Emails sent and received in the current billing period.

limit integer

The monthly plan limit.

sent integer

Emails sent this billing period.

received integer

Emails received this billing period.

resets_at string

When the monthly counter resets, as an ISO 8601 datetime.

contacts object

2 fields

used integer

Contacts currently stored.

limit integer

The plan limit.

segments object

2 fields

used integer

Segments currently created.

limit integer

nullable

The plan limit, or null when the account has a contacts subscription.

broadcasts object

2 fields

used integer

Broadcasts sent.

limit

nullable

Always null; broadcasts aren't limited.

ai_credits object

3 fields

used integer

AI credits consumed in the current period.

limit integer

nullable

The plan limit, or null when unlimited.

next_increase_at string

nullable

When the AI credit balance next increases, as an ISO 8601 datetime, or null when unknown.

automation_runs object

3 fields

used integer

Automation runs in the current billing period.

limit integer

The plan limit.

resets_at string

When the counter resets, as an ISO 8601 datetime.

domains object

2 fields

used integer

Domains currently added.

limit integer

nullable

The plan limit, or null when unlimited.

rate_limit object

2 fields

limit integer

The number of requests allowed per duration.

duration string

The rate-limit window, e.g. '1000ms'.

200 Response

{
  "object": "usage",
  "emails": {
    "daily": {
      "used": 0,
      "limit": 0,
      "sent": 0,
      "received": 0,
      "resets_at": "string"
    },
    "monthly": {
      "used": 0,
      "limit": 0,
      "sent": 0,
      "received": 0,
      "resets_at": "string"
    }
  },
  "contacts": {
    "used": 0,
    "limit": 0
  },
  "segments": {
    "used": 0,
    "limit": 0
  },
  "broadcasts": {
    "used": 0,
    "limit": null
  },
  "ai_credits": {
    "used": 0,
    "limit": 0,
    "next_increase_at": "string"
  },
  "automation_runs": {
    "used": 0,
    "limit": 0,
    "resets_at": "string"
  },
  "domains": {
    "used": 0,
    "limit": 0
  },
  "rate_limit": {
    "limit": 0,
    "duration": "string"
  }
}

Example generated from the schema

Inboxes

Create and manage Inboxes through the Resend API. A sending access key can call only these Inboxes endpoints: POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/reply, POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/forward, POST /inboxes/{inbox_id}/drafts and POST /inboxes/{inbox_id}/drafts/{draft_id}/send. When the key is limited to one domain, the inbox address must be on that domain, or the request returns a 403. Every other Inboxes endpoint needs a full access API key, and a sending access key returns a 401 restricted_api_key.

Retrieve a list of inboxes

GET /inboxes

Returns the inboxes of the team, newest first. The list items carry fewer fields than a single inbox. Retrieve an inbox to get all its fields. The after and before cursors take an inbox ID, and only one of them can be passed, or the request returns a 422. A value that is not a UUID returns a 422, and an unknown ID returns a 404.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListInboxesResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of object

Array containing inbox information.

1 field

items object

8 fields

id string · uuid

The ID of the inbox.

name string

nullable

Internal name for the inbox. Recipients do not see it.

email_address string

The address of the inbox.

from_name string

nullable

The name recipients see when mail is sent from this inbox. null when not set.

unread integer

The number of unread threads in the Inbox folder.

last_received string · date-time

nullable

ISO 8601 timestamp of the newest received email in the Inbox folder. null when the folder has no received email.

created_at string · date-time

ISO 8601 timestamp when the inbox was created.

updated_at string · date-time

ISO 8601 timestamp when the inbox was last updated.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1",
      "name": "Customer Support",
      "email_address": "support@acme.com",
      "from_name": "Ada from Support",
      "unread": 3,
      "last_received": "2026-08-05T14:03:11.229Z",
      "created_at": "2026-08-01T09:12:44.512Z",
      "updated_at": "2026-08-03T10:20:05.118Z"
    }
  ]
}

Example generated from the schema

Create an inbox

POST /inboxes

Creates an inbox that sends and receives email at an address on one of your domains. The domain must belong to the team. Without forwarding, the domain must have receiving enabled, with DKIM and SPF verified and the inbound MX record verified or pending. With forwarding set to true, the domain only needs DKIM and SPF verified for sending, and Resend generates a receiving_address on the team inbound domain, and a team without an inbound domain gets a 422. A domain that does not meet these rules returns a 422 validation_error. An address or receiving address that is already in use returns a 409. A team that has reached the inbox limit of its plan returns a 403 validation_error. A blocked account returns a 451.

Request body CreateInboxOptions

email_address string

The inbox email address on one of your domains. The API trims and lowercases it. The part before the @ is at most 64 characters and contains only letters, numbers, and . _ % -. A + returns a 422. It cannot start or end with a dot or contain two dots in a row.

name string

Internal name for the inbox. Recipients do not see it. Max 64 characters. Defaults to email_address.

rules max length 64

from_name string

The name recipients see when mail is sent from this inbox. A plain name, not a Name <email> address. Max 78 characters. It cannot contain a colon, <, >, line breaks, or other control characters. An email address inside the name must be on a domain the team has verified for sending. An empty string leaves it unset.

rules max length 78

forwarding boolean

When true, Resend provisions a receiving address so you can receive mail without adding an MX record. The address is returned in receiving_address.

default false

Responses

201

CreateInboxResponseSuccess

object string

Type of the response object.

id string · uuid

The ID of the inbox.

POST /inboxes

{
  "email_address": "support@acme.com",
  "name": "Customer Support",
  "from_name": "Ada from Support",
  "forwarding": false
}

Example generated from the schema

201 Response

{
  "object": "inbox",
  "id": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"
}

Example generated from the schema

Retrieve a single inbox by ID or email address

GET /inboxes/{inbox_id}

Path parameters

inbox_id string

The Inbox ID or the inbox email address, such as support@acme.com. A value that contains @ must be a valid email address, and any other value must be a UUID, or the request returns a 422. The address match is case-insensitive and never falls back to the inbox name. An address that matches no inbox returns a 404.

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Responses

200

GetInboxResponseSuccess

object string

The object type. Always inbox.

id string · uuid

The ID of the inbox.

name string

Internal name for the inbox. Recipients do not see it. Falls back to the inbox email address.

email_address string

The address of the inbox.

domain_id string · uuid

The ID of the domain that owns the address.

receiving_address string

nullable

The address to forward mail to when forwarding is enabled. null otherwise.

from_name string

nullable

The name recipients see when mail is sent from this inbox. null when not set.

unread integer

The number of unread threads in the Inbox folder.

drafts integer

The number of unsent drafts.

last_received string · date-time

nullable

ISO 8601 timestamp of the newest received email in the Inbox folder. null when the folder has no received email.

created_at string · date-time

ISO 8601 timestamp when the inbox was created.

updated_at string · date-time

ISO 8601 timestamp when the inbox was last updated.

200 Response

{
  "object": "inbox",
  "id": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1",
  "name": "Customer Support",
  "email_address": "support@acme.com",
  "domain_id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "receiving_address": null,
  "from_name": "Ada from Support",
  "unread": 3,
  "drafts": 2,
  "last_received": "2026-08-05T14:03:11.229Z",
  "created_at": "2026-08-01T09:12:44.512Z",
  "updated_at": "2026-08-03T10:20:05.118Z"
}

Example generated from the schema

Update an existing inbox by ID or email address

PATCH /inboxes/{inbox_id}

Updates the internal name of the inbox or the name recipients see when mail is sent from it. At least one of name or from_name is required.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Request body UpdateInboxOptions

Provide at least one of name or from_name.

name string

New internal name for the inbox. Recipients do not see it. Between 1 and 64 characters after trimming.

rules min length 1max length 64

from_name string

rules max length 78

any of · 1

any of · 2

Responses

200

UpdateInboxResponseSuccess

object string

The object type.

id string · uuid

The ID of the inbox.

PATCH /inboxes/{inbox_id}

null

Example generated from the schema

200 Response

{
  "object": "inbox",
  "id": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"
}

Example generated from the schema

Remove an existing inbox by ID or email address

DELETE /inboxes/{inbox_id}

Removes the inbox. An inbox that does not exist or was already removed returns a 404 not_found.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Responses

200

RemoveInboxResponseSuccess

object string

The object type.

id string · uuid

The ID of the inbox.

deleted boolean

Indicates whether the inbox was successfully deleted.

200 Response

{
  "object": "inbox",
  "id": "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1",
  "deleted": true
}

Example generated from the schema

Retrieve the agent settings for an inbox

GET /inboxes/{inbox_id}/agent

Returns the agent settings of the inbox. An inbox without a configured agent returns empty settings: instructions and tone are null and actions is an empty array.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Responses

200

GetInboxAgentResponseSuccess

object string

The object type. Always inbox_agent.

instructions string

nullable

Instructions the agent follows when it handles the threads of the inbox. Null when no instructions are set.

tone string

nullable

The tone the agent writes in. Null when no tone is set.

enum concise_professionalconcise_casualexpanded_professionalexpanded_casualnull

actions array of string

The actions the agent can take, in the order of the enum. Empty when no actions are enabled.

1 field

items string

enum draft_replyforward_threadadd_labelsassign_threadmark_as_spamarchivemove_to_trash

200 Response

{
  "object": "inbox_agent",
  "instructions": "Answer refund questions yourself. Escalate legal threats.",
  "tone": "concise_professional",
  "actions": [
    "draft_reply",
    "add_labels"
  ]
}

Example generated from the schema

Update the agent settings for an inbox

PATCH /inboxes/{inbox_id}/agent

Updates the agent settings of the inbox. The agent is created when the inbox has none. Omitted fields keep their current value.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Request body UpdateInboxAgentOptions

At least one of instructions, tone, or actions must be provided. Omitted fields keep their current value.

instructions string

nullable

Instructions the agent follows when it handles the threads of the inbox. Max 4000 characters. Leading and trailing whitespace is trimmed, and the trimmed value must not be empty. Send null to clear the instructions.

rules min length 1max length 4000

tone string

nullable

The tone the agent writes in. Send null to clear the tone.

enum concise_professionalconcise_casualexpanded_professionalexpanded_casualnull

actions array of string

The actions the agent can take. Replaces the whole set. Duplicates are removed. Send an empty array to disable all actions. The old names archive_thread and delete_thread return a 422. Use archive and move_to_trash.

1 field

items string

enum draft_replyforward_threadadd_labelsassign_threadmark_as_spamarchivemove_to_trash

any of · 1

any of · 2

any of · 3

Responses

200

UpdateInboxAgentResponseSuccess

object string

The object type. Always inbox_agent.

id string · uuid

The ID of the inbox agent.

PATCH /inboxes/{inbox_id}/agent

null

Example generated from the schema

200 Response

{
  "object": "inbox_agent",
  "id": "a1f84a4e-6f2b-4f0a-9c1d-8a2e5b3c7d90"
}

Example generated from the schema

Retrieve a list of inbox labels

GET /inboxes/{inbox_id}/labels

Returns every label on the inbox, oldest first. The list is not paginated.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Responses

200

ListInboxLabelsResponseSuccess

object string

Type of the response object.

data array of InboxLabel

The labels on the inbox, oldest first.

1 field

items InboxLabel

4 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

created_at string · date-time

Timestamp when the label was created.

200 Response

{
  "object": "list",
  "data": [
    {
      "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
      "name": "Urgent",
      "color": "#E93D82",
      "created_at": "2026-08-05T14:07:42.881Z"
    }
  ]
}

Example generated from the schema

Create a label on an inbox

POST /inboxes/{inbox_id}/labels

A label is a named, colored tag that belongs to one inbox. An inbox can have at most 100 labels. Label names are unique per inbox, compared without case. A duplicate name or a full inbox returns a 422 validation_error.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Request body CreateInboxLabelOptions

name string

The name of the label. Max 64 characters. Leading and trailing whitespace is trimmed. Must not match another label on the inbox, compared without case.

rules min length 1max length 64

color string

The color of the label, as a #RRGGBB hex color. It is stored in uppercase. When omitted, a random color from the dashboard palette is used.

rules pattern ^#[0-9A-Fa-f]{6}$

Responses

201

CreateInboxLabelResponseSuccess

object string

Type of the response object.

id string · uuid

The ID of the label.

POST /inboxes/{inbox_id}/labels

{
  "name": "Urgent",
  "color": "#E93D82"
}

Example generated from the schema

201 Response

{
  "object": "inbox_label",
  "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34"
}

Example generated from the schema

Update an existing inbox label

PATCH /inboxes/{inbox_id}/labels/{label_id}

Renames or recolors a label. Omitted fields keep their current value. A new name must not match another label on the inbox, compared without case, or the request returns a 422 validation_error.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

label_id string · uuid

The Label ID.

Request body UpdateInboxLabelOptions

name string

A new name for the label. Max 64 characters. Leading and trailing whitespace is trimmed. Must not match another label on the inbox, compared without case.

rules min length 1max length 64

color string

A new color for the label, as a #RRGGBB hex color. It is stored in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

Responses

200

UpdateInboxLabelResponseSuccess

object string

Type of the response object.

id string · uuid

The ID of the updated label.

PATCH /inboxes/{inbox_id}/labels/{label_id}

{
  "name": "Billing",
  "color": "#F76B15"
}

Example generated from the schema

200 Response

{
  "object": "inbox_label",
  "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34"
}

Example generated from the schema

Remove an existing inbox label

DELETE /inboxes/{inbox_id}/labels/{label_id}

Deletes the label and removes it from every thread that carries it.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

label_id string · uuid

The Label ID.

Responses

200

RemoveInboxLabelResponseSuccess

object string

Type of the response object.

id string · uuid

The ID of the removed label.

deleted boolean

Indicates whether the label was deleted.

200 Response

{
  "object": "inbox_label",
  "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
  "deleted": true
}

Example generated from the schema

Retrieve a list of inbox threads

GET /inboxes/{inbox_id}/threads

Returns the threads in an inbox, most recently active first. A thread is a conversation made up of one or more emails. The after and before cursors take a thread ID, and only one of them can be passed. A cursor that is not a UUID, such as a date, returns a 422 validation_error. A cursor thread that is not in the selected folders returns a 404. To find threads by text, sender, recipient, attachment, or date, use the search threads endpoint.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Query parameters

folders array of string

Comma-separated folders to list, for example inbox,sent. Repeating the parameter returns a 422 validation_error. A thread is returned when any of its emails is in one of the folders, so a thread in inbox with an email you sent matches both inbox and sent. Defaults to inbox, or to inbox,archive,sent when labels is set. spam and trash are only included when you name them.

example

[
  "inbox",
  "sent"
]

1 field

items string

enum inboxarchivespamsenttrash

labels array of string

Comma-separated label IDs. Returns threads with any of these labels. Up to 50 IDs. An ID that does not exist in the inbox returns a 404. Repeating the parameter returns a 422 validation_error.

rules max items 50

example

[
  "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34"
]

1 field

items string · uuid

read boolean

true returns threads where every email is read. false returns threads with at least one unread email. Only the literal values true and false are accepted.

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListInboxThreadsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of InboxThread

The matching threads, most recently active first.

1 field

items InboxThread

A thread as it appears in the list of an inbox's threads.

13 fields

id string · uuid

The ID of the thread.

subject string

nullable

The subject of the thread.

from string

nullable

The sender email address. Can include the display name.

to array of string

The recipients of the most recent email. For a received email, these are the addresses it was delivered to, not the full To header.

1 field

items string

cc array of string

The CC recipients of the most recent email.

1 field

items string

bcc array of string

The BCC recipients of the most recent email. Always empty for a received email.

1 field

items string

labels array of InboxThreadLabel

The labels attached to the thread.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

email_count integer

The number of emails in the thread.

has_attachment boolean

Whether the most recent email in the thread has an attachment.

has_draft boolean

Whether the thread has an unsent draft.

read boolean

True only when every email in the thread is read.

received_at string · date-time

Timestamp when the thread was last active.

folder string

The folder the thread is in. Every thread is in exactly one folder. inbox holds threads with at least one received email. archive and spam hold threads moved there. trash holds threads scheduled for deletion in 30 days. sent holds threads whose emails are all outbound, and is assigned automatically.

enum inboxarchivespamsenttrash

200 Response

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12",
      "subject": "Refund for order 1041",
      "from": "ada@example.org",
      "to": [
        "support@example.com"
      ],
      "cc": [],
      "bcc": [],
      "labels": [
        {
          "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
          "name": "Urgent",
          "color": "#E93D82"
        }
      ],
      "email_count": 2,
      "has_attachment": true,
      "has_draft": false,
      "read": false,
      "received_at": "2026-08-05T14:03:11.229Z",
      "folder": "inbox"
    }
  ]
}

Example generated from the schema

Search the threads of an inbox

GET /inboxes/{inbox_id}/threads/search

Finds threads by the text of their emails, who sent or received them, whether they have attachments, and their dates. Results are ordered by latest activity, newest first, and paginate like the list threads endpoint, so a cursor that is not a thread ID returns a 422. Search can be up to about a minute behind new emails. Different parameters combine, so a thread must match all of them. folders, labels, and read apply to the thread. query, from, to, cc, bcc, has_attachment, start_date, and end_date must all match the same email in the thread. When any of these email filters is set, the matching email must itself be in one of folders. For sent, that means an email the inbox sent. When more than 10,000 threads match, search covers the 10,000 with the newest matching email.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Query parameters

query string

Free text to search for in the subject, body, sender, recipients, and attachment names. Every word must match. Wrap words in double quotes to match an exact phrase. Start a word or quoted phrase with - to exclude it. Max 256 characters and 32 words.

rules max length 256

example "invoice -draft"

from array of string

Comma-separated senders. Each value matches part of the sender's address or name, without case. Returns threads that match any of them. Up to 20 values. Repeating the parameter returns a 422 validation_error.

rules max items 20

example

[
  "isabella@example.com",
  "carolina@example.com"
]

1 field

items string

to array of string

Comma-separated recipients, matched the same way as from. Up to 20 values. Repeating the parameter returns a 422 validation_error.

rules max items 20

1 field

items string

cc array of string

Comma-separated CC recipients, matched the same way as from. Up to 20 values. Repeating the parameter returns a 422 validation_error.

rules max items 20

1 field

items string

bcc array of string

Comma-separated BCC recipients, matched the same way as from. Up to 20 values. Repeating the parameter returns a 422 validation_error.

rules max items 20

1 field

items string

has_attachment boolean

true matches emails with an attachment. false matches emails without one. Only the literal values true and false are accepted.

start_date string

Matches emails sent on or after this date. Accepts a date like 2026-09-01 or an ISO 8601 timestamp, in UTC unless the timestamp has an offset. An empty value returns a 422.

example "2026-09-01"

end_date string

Matches emails sent on or before this date. Same formats as start_date. A date covers that whole day, so start_date=2026-09-01&end_date=2026-09-30 covers all of September. A timestamp is used as given. An end_date before start_date returns a 422 validation_error. An empty value returns a 422.

example "2026-09-30"

folders array of string

Comma-separated folders to search, for example inbox,sent. Repeating the parameter returns a 422 validation_error. A thread is returned when any of its emails is in one of the folders. Defaults to inbox, or to inbox,archive,sent when labels is set. spam and trash are only included when you name them.

example

[
  "inbox",
  "sent"
]

1 field

items string

enum inboxarchivespamsenttrash

labels array of string

Comma-separated label IDs. Returns threads with any of these labels. Up to 50 IDs. An ID that does not exist in the inbox returns a 404. Repeating the parameter returns a 422 validation_error.

rules max items 50

example

[
  "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34"
]

1 field

items string · uuid

read boolean

true returns threads where every email is read. false returns threads with at least one unread email. Only the literal values true and false are accepted.

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

SearchInboxThreadsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of InboxThreadSearchResult

The matching threads, most recently active first.

1 field

items InboxThreadSearchResult

A thread as it appears in the list of an inbox's threads.

14 fields

id string · uuid

The ID of the thread.

subject string

nullable

The subject of the thread.

from string

nullable

The sender email address. Can include the display name.

to array of string

The recipients of the most recent email. For a received email, these are the addresses it was delivered to, not the full To header.

1 field

items string

cc array of string

The CC recipients of the most recent email.

1 field

items string

bcc array of string

The BCC recipients of the most recent email. Always empty for a received email.

1 field

items string

labels array of InboxThreadLabel

The labels attached to the thread.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

email_count integer

The number of emails in the thread.

has_attachment boolean

Whether the most recent email in the thread has an attachment.

has_draft boolean

Whether the thread has an unsent draft.

read boolean

True only when every email in the thread is read.

received_at string · date-time

Timestamp when the thread was last active.

folder string

enum inboxarchivespamsenttrash

matched_email_id string · uuid

nullable

The ID of the email in the thread that matched the search. When query has words or phrases, it is the most relevant match. Otherwise, it is the newest. It is the same id that the list thread emails endpoint returns, so use it as email_id with the get, reply and forward endpoints. Null when the search index returns no matched email for the thread.

200 Response

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12",
      "subject": "Refund for order 1041",
      "from": "ada@example.org",
      "to": [
        "support@example.com"
      ],
      "cc": [],
      "bcc": [],
      "labels": [
        {
          "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
          "name": "Urgent",
          "color": "#E93D82"
        }
      ],
      "email_count": 2,
      "has_attachment": true,
      "has_draft": false,
      "read": false,
      "received_at": "2026-08-05T14:03:11.229Z",
      "folder": "inbox",
      "matched_email_id": "e8a3f1c6-2b9d-4e5a-a7c4-9d1b6f3e2a80"
    }
  ]
}

Example generated from the schema

Retrieve a single inbox thread

GET /inboxes/{inbox_id}/threads/{thread_id}

Returns the thread summary. The emails in the thread are listed with the list thread emails endpoint.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

Responses

200

GetInboxThreadResponseSuccess

The summary of a single thread.

object string

The object type.

id string · uuid

The ID of the thread.

subject string

nullable

The subject of the thread.

folder string

The folder the thread is in.

enum inboxarchivespamsenttrash

labels array of InboxThreadLabel

The labels attached to the thread.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

read boolean

True only when every email in the thread is read.

200 Response

{
  "object": "inbox_thread",
  "id": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12",
  "subject": "Refund for order 1041",
  "folder": "inbox",
  "labels": [
    {
      "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
      "name": "Urgent",
      "color": "#E93D82"
    }
  ],
  "read": false
}

Example generated from the schema

Update an existing inbox thread

PATCH /inboxes/{inbox_id}/threads/{thread_id}

Marks a thread read or unread, or moves it to a folder. At least one of read or folder is required. To change the labels of a thread, use the add, set, and remove thread labels endpoints. This endpoint ignores the removed add_label_ids and remove_label_ids fields, so a body with only those fields returns a 422 validation_error. Moving a thread out of trash restores it and clears its deletion deadline. The changes apply in this order: read, then folder. They are not atomic.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

Request body UpdateInboxThreadOptions

At least one of read or folder is required. Use the thread labels endpoints to change labels.

read boolean

Marks every email in the thread read or unread.

folder string

Moves the thread to this folder. sent is assigned automatically and cannot be set.

enum inboxarchivespamtrash

any of · 1

any of · 2

Responses

200

UpdateInboxThreadResponseSuccess

The summary of a single thread.

object string

The object type.

id string · uuid

The ID of the thread.

subject string

nullable

The subject of the thread.

folder string

The folder the thread is in.

enum inboxarchivespamsenttrash

labels array of InboxThreadLabel

The labels attached to the thread.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

read boolean

True only when every email in the thread is read.

PATCH /inboxes/{inbox_id}/threads/{thread_id}

null

Example generated from the schema

200 Response

{
  "object": "inbox_thread",
  "id": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12",
  "subject": "Refund for order 1041",
  "folder": "inbox",
  "labels": [
    {
      "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
      "name": "Urgent",
      "color": "#E93D82"
    }
  ],
  "read": false
}

Example generated from the schema

Remove an existing inbox thread

DELETE /inboxes/{inbox_id}/threads/{thread_id}

Moves the thread to trash and schedules it for deletion in 30 days. This is reversible. To restore the thread, update its folder to inbox, archive, or spam, which also clears the deletion deadline.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

Responses

200

RemoveInboxThreadResponseSuccess

object string

The object type.

id string · uuid

The ID of the thread.

deleted boolean

True when this call moved the thread to trash. False when the thread was already there.

200 Response

{
  "object": "inbox_thread",
  "id": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12",
  "deleted": true
}

Example generated from the schema

Add labels to an inbox thread

POST /inboxes/{inbox_id}/threads/{thread_id}/labels

Applies one or more labels to the thread. Labels already on the thread stay on it. The response lists every label on the thread after the change. A label ID that is not a label of the inbox returns a 404 Label not found., and nothing changes. A thread that does not exist in the inbox returns a 404 Thread not found.. To replace the labels of the thread, use the set thread labels endpoint.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

Request body AddInboxThreadLabelsOptions

labels array of string

The IDs of the labels to apply to the thread. Between 1 and 10 IDs, each a label of the inbox.

rules min items 1max items 10

1 field

items string · uuid

Responses

200

AddInboxThreadLabelsResponseSuccess

object string

Type of the response object.

data array of InboxThreadLabel

Every label on the thread after the change.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

POST /inboxes/{inbox_id}/threads/{thread_id}/labels

{
  "labels": [
    "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34"
  ]
}

Example generated from the schema

200 Response

{
  "object": "list",
  "data": [
    {
      "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
      "name": "Urgent",
      "color": "#E93D82"
    }
  ]
}

Example generated from the schema

Set the labels of an inbox thread

PUT /inboxes/{inbox_id}/threads/{thread_id}/labels

Replaces every label on the thread with the given labels, in one atomic change. Labels on the thread that are not in the list are taken off it. The labels themselves are kept. An empty array takes every label off the thread. The response lists every label on the thread after the change. A label ID that is not a label of the inbox returns a 404 Label not found., and nothing changes. A thread that does not exist in the inbox returns a 404 Thread not found..

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

Request body SetInboxThreadLabelsOptions

labels array of string

The IDs of the labels the thread carries after the change. Up to 100 IDs, each a label of the inbox. Pass an empty array to take every label off the thread.

rules max items 100

1 field

items string · uuid

Responses

200

SetInboxThreadLabelsResponseSuccess

object string

Type of the response object.

data array of InboxThreadLabel

Every label on the thread after the change.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

PUT /inboxes/{inbox_id}/threads/{thread_id}/labels

{
  "labels": [
    "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34"
  ]
}

Example generated from the schema

200 Response

{
  "object": "list",
  "data": [
    {
      "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
      "name": "Urgent",
      "color": "#E93D82"
    }
  ]
}

Example generated from the schema

Remove a label from an inbox thread

DELETE /inboxes/{inbox_id}/threads/{thread_id}/labels/{label_id}

Takes one label off the thread. The label itself is kept, and stays on every other thread that carries it. To delete the label, use the remove inbox label endpoint. The response lists every label on the thread after the change. A label that is not on the thread returns a 200 with the current labels. A label ID that is not a label of the inbox returns a 404 Label not found.. A thread that does not exist in the inbox returns a 404 Thread not found..

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

label_id string · uuid

The Label ID.

Responses

200

RemoveInboxThreadLabelResponseSuccess

object string

Type of the response object.

data array of InboxThreadLabel

Every label on the thread after the change.

1 field

items InboxThreadLabel

3 fields

id string · uuid

The ID of the label.

name string

The name of the label.

color string

The color of the label, as a #RRGGBB hex color in uppercase.

rules pattern ^#[0-9A-Fa-f]{6}$

200 Response

{
  "object": "list",
  "data": [
    {
      "id": "7f9c1d2e-4a6b-4c3d-8e15-9b0a7c6d5e34",
      "name": "Urgent",
      "color": "#E93D82"
    }
  ]
}

Example generated from the schema

Retrieve a list of thread emails

GET /inboxes/{inbox_id}/threads/{thread_id}/emails

Returns the messages of a thread, oldest first. Pass the id of the last message as after to get the next, newer page. Pass the id of the first message as before to get the previous, older page. Passing both after and before, or a cursor that is not a UUID, returns a 422. A cursor that is not a message of the thread returns a 404.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListInboxThreadEmailsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of InboxThreadEmail

The messages of the thread on this page, oldest first.

1 field

items InboxThreadEmail

14 fields

id string · uuid

The ID of the message.

direction string

Whether the inbox received the message (inbound) or sent it (outbound). A message the inbox sent to itself is inbound, so a reply to it goes to its sender.

enum inboundoutbound

from string

Sender email address. Includes the display name when the sender has one, in the format "Name sender@domain.com".

to array of string

The recipients of the message. For a received message, these are the addresses it was delivered to, not the full To header.

1 field

items string

cc array of string

The CC recipients of the message.

1 field

items string

bcc array of string

The BCC recipients of the message. Always empty for a received message.

1 field

items string

reply_to array of string

The Reply-To addresses of the message.

1 field

items string

subject string

nullable

The subject of the message.

message_id string

nullable

The Message-ID header of the message.

html string

nullable

The HTML body.

text string

nullable

The plain-text body.

attachments array of InboxThreadEmailAttachment

The attachments of the message.

1 field

items InboxThreadEmailAttachment

3 fields

id string

The ID of the attachment.

filename string

nullable

The filename of the attachment.

size integer

nullable

The size of the attachment in bytes.

read boolean

Whether the message has been read.

received_at string · date-time

Timestamp when the inbox received the message, or when the inbox sent it.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "5b1a9f47-2c8d-4e6f-9a03-1d2e3f4a5b60",
      "direction": "inbound",
      "from": "Ada Lovelace <ada@example.org>",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": [
        "replies@example.org"
      ],
      "subject": "Refund for order 1041",
      "message_id": "<1041@example.org>",
      "html": "<p>Could I get a refund for order 1041?</p>",
      "text": "Could I get a refund for order 1041?",
      "attachments": [
        {
          "id": "9d4f2b81-6c3a-4e7d-8b12-0a5c6d7e8f90",
          "filename": "receipt.pdf",
          "size": 20841
        }
      ],
      "read": false,
      "received_at": "2026-08-05T14:03:11.229Z"
    }
  ]
}

Example generated from the schema

Retrieve a single thread email

GET /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

email_id string · uuid

The Email ID, as returned in data[].id by the list thread emails endpoint.

Responses

200

GetInboxThreadEmailResponseSuccess

id string · uuid

The ID of the message.

direction string

Whether the inbox received the message (inbound) or sent it (outbound). A message the inbox sent to itself is inbound, so a reply to it goes to its sender.

enum inboundoutbound

from string

Sender email address. Includes the display name when the sender has one, in the format "Name sender@domain.com".

to array of string

The recipients of the message. For a received message, these are the addresses it was delivered to, not the full To header.

1 field

items string

cc array of string

The CC recipients of the message.

1 field

items string

bcc array of string

The BCC recipients of the message. Always empty for a received message.

1 field

items string

reply_to array of string

The Reply-To addresses of the message.

1 field

items string

subject string

nullable

The subject of the message.

message_id string

nullable

The Message-ID header of the message.

html string

nullable

The HTML body.

text string

nullable

The plain-text body.

attachments array of InboxThreadEmailAttachment

The attachments of the message.

1 field

items InboxThreadEmailAttachment

3 fields

id string

The ID of the attachment.

filename string

nullable

The filename of the attachment.

size integer

nullable

The size of the attachment in bytes.

read boolean

Whether the message has been read.

received_at string · date-time

Timestamp when the inbox received the message, or when the inbox sent it.

200 Response

{
  "id": "5b1a9f47-2c8d-4e6f-9a03-1d2e3f4a5b60",
  "direction": "inbound",
  "from": "Ada Lovelace <ada@example.org>",
  "to": [
    "support@acme.com"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": [
    "replies@example.org"
  ],
  "subject": "Refund for order 1041",
  "message_id": "<1041@example.org>",
  "html": "<p>Could I get a refund for order 1041?</p>",
  "text": "Could I get a refund for order 1041?",
  "attachments": [
    {
      "id": "9d4f2b81-6c3a-4e7d-8b12-0a5c6d7e8f90",
      "filename": "receipt.pdf",
      "size": 20841
    }
  ],
  "read": false,
  "received_at": "2026-08-05T14:03:11.229Z"
}

Example generated from the schema

Reply to a thread email

POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/reply

Sends a reply from the inbox address right away, with no stored draft. The to recipients come from the message you reply to. For a message the inbox received, the reply goes to its Reply-To addresses, or to its sender when it has no Reply-To. For a message the inbox sent, the reply goes to that message's to recipients. Set reply_all to also copy the other recipients of the message. The reply threads under the message through the In-Reply-To and References headers. When no recipient can be found for the reply, the request returns a 422. The whole email, encoded, can be at most 40 MB, or the request returns a 422.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

email_id string · uuid

The Email ID of the message to reply to, as returned in data[].id by the list thread emails endpoint.

Header parameters

Idempotency-Key string

A unique key for the request, so the reply is sent only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the idempotent-replayed: true header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 invalid_idempotency_key. Learn more

rules min length 1max length 256

Request body ReplyInboxThreadEmailOptions

At least one of html or text must contain more than whitespace.

cc one of

CC recipient email address. For multiple addresses, send as an array of strings. Without reply_all, the reply copies only these addresses. With reply_all, these addresses are merged with the copied recipients, without duplicates. cc and bcc combined must be fewer than 50 addresses. After the to recipients are added, the reply cannot exceed 50 recipients. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 49

1 field

items string

one of · 3

nullable

bcc one of

BCC recipient email address. For multiple addresses, send as an array of strings. BCC recipients of the original message are never copied. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 49

1 field

items string

one of · 3

nullable

html string

The HTML body of the reply.

text string

The plain-text body of the reply.

subject string

The subject of the reply. Cannot be only whitespace or contain a line break. When omitted, the thread subject is used, prefixed with Re: if it does not already start with it.

rules min length 1max length 2000

reply_all boolean

Reply to everyone on the original message. For a message the inbox received, the reply goes to its Reply-To addresses, or to its sender when it has none, and copies the other addresses of its To header and its cc recipients in cc. For a message the inbox sent, the reply goes to that message's Reply-To addresses when they are not the inbox address, otherwise to its to recipients, and copies its cc recipients. The inbox address is always excluded, and duplicates are removed.

default false

attachments array of Attachment

nullable

Files to attach, as on POST /emails. Each one needs content or path. The content of all files can total at most 25 MB. A path file does not count toward the 25 MB, because it is fetched when the email is sent. An empty file, a blocked file type, a path that does not start with http or that starts with http://localhost:, or a content_type that is not a valid MIME type returns a 422. Other path problems fail the email when it is sent, not the request.

1 field

items Attachment

5 fields

content string · binary

Content of an attached file.

filename string

Name of attached file.

path string

Path where the attachment file is hosted

content_type string

Optional content type for the attachment, if not set it will be derived from the filename property

content_id string

Content ID for embedding inline images using cid references (e.g., cid:image001).

headers object

nullable

Custom headers to add to the email. The In-Reply-To, References and Reply-To headers are set by Resend and cannot be set here. Sending one of them, in any letter case, returns a 422. Header names cannot be empty, and names and values cannot contain line breaks or null characters, or the request returns a 422. null means no custom headers.

1 field

additional properties string

any of · 1

any of · 2

Responses

200

ReplyInboxThreadEmailResponseSuccess

id string · uuid

The ID of the sent email. Use it with the emails endpoints.

POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/reply

null

Example generated from the schema

200 Response

{
  "id": "6a0c8e58-3d9e-4f7a-8b14-2e3f4a5b6c71"
}

Example generated from the schema

Forward a thread email

POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/forward

Forwards a message from the inbox address right away, with no stored draft. The original message is quoted under a forwarded-message banner, below the optional html or text note. The attachments of the original message are sent with the forward, together with any attachments you add. The request returns a 422 when they exceed 25 MB of content in total. An original attachment that was sent from a URL (path) cannot be forwarded, and the request returns a 422. The whole email, encoded, can be at most 40 MB, or the request returns a 422.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

thread_id string · uuid

The Thread ID.

email_id string · uuid

The Email ID of the message to forward, as returned in data[].id by the list thread emails endpoint.

Header parameters

Idempotency-Key string

A unique key for the request, so the forward is sent only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the idempotent-replayed: true header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 invalid_idempotency_key. Learn more

rules min length 1max length 256

Request body ForwardInboxThreadEmailOptions

to one of

Recipient email address. For multiple addresses, send as an array of strings. Must name at least one address. to, cc and bcc combined cannot exceed 50 recipients. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

2 fields

one of · 1 string

one of · 2 array of string

rules min items 1max items 50

1 field

items string

cc one of

CC recipient email address. For multiple addresses, send as an array of strings. Counts toward the 50-recipient limit. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

bcc one of

BCC recipient email address. For multiple addresses, send as an array of strings. Counts toward the 50-recipient limit. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

html string

An HTML note sent above the quoted original.

text string

A plain-text note sent above the quoted original.

subject string

The subject of the forward. Cannot be only whitespace or contain a line break. When omitted, the thread subject is used, prefixed with Fwd: if it does not already start with it.

rules min length 1max length 2000

attachments array of Attachment

nullable

Files to attach, as on POST /emails. Each one needs content or path. They share one limit with the attachments of the original message, which the forward also sends. Together they can have at most 25 MB of content. A path file does not count toward the 25 MB, because it is fetched when the email is sent. An empty file, a blocked file type, a path that does not start with http or that starts with http://localhost:, or a content_type that is not a valid MIME type returns a 422. Other path problems fail the email when it is sent, not the request.

1 field

items Attachment

5 fields

content string · binary

Content of an attached file.

filename string

Name of attached file.

path string

Path where the attachment file is hosted

content_type string

Optional content type for the attachment, if not set it will be derived from the filename property

content_id string

Content ID for embedding inline images using cid references (e.g., cid:image001).

headers object

nullable

1 field

additional properties string

Responses

200

ForwardInboxThreadEmailResponseSuccess

id string · uuid

The ID of the sent email. Use it with the emails endpoints.

POST /inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/forward

{
  "to": [
    "colleague@example.org"
  ],
  "cc": [
    "billing@acme.com"
  ],
  "bcc": [
    "records@acme.com"
  ],
  "html": "<p>Flagging this refund request for you.</p>",
  "text": "Flagging this refund request for you.",
  "subject": "Fwd: Refund for order 1041",
  "attachments": [
    {
      "content": "<binary>",
      "filename": "string",
      "path": "string",
      "content_type": "string",
      "content_id": "string"
    }
  ],
  "headers": {
    "X-Ticket-Id": "4821"
  }
}

Example generated from the schema

200 Response

{
  "id": "6a0c8e58-3d9e-4f7a-8b14-2e3f4a5b6c71"
}

Example generated from the schema

Retrieve a list of drafts

GET /inboxes/{inbox_id}/drafts

Returns the unsent drafts on the inbox, most recently updated first. The after and before cursors take a Draft ID from the current page, and only one of them can be passed. A cursor that is not a UUID, or both cursors together, return a 422. A cursor that is not an unsent draft on this inbox returns a 404.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Query parameters

limit integer

Number of items to return.

rules min 1max 100

after string

Return items after this cursor.

before string

Return items before this cursor.

Responses

200

ListInboxDraftsResponseSuccess

object string

Type of the response object.

has_more boolean

Indicates if there are more results available.

data array of InboxDraftListItem

The unsent drafts on this page, most recently updated first.

1 field

items InboxDraftListItem

11 fields

id string · uuid

The ID of the draft.

type string

reply when the draft replies to an email in an existing thread. standalone when the draft starts a new thread.

enum standalonereply

to array of string

nullable

The recipients. null or empty when no recipients are set.

1 field

items string

cc array of string

The CC recipients.

1 field

items string

bcc array of string

The BCC recipients.

1 field

items string

subject string

nullable

The subject.

snippet string

nullable

A short preview of the body.

thread_id string · uuid

nullable

The Thread ID when the draft is a reply. null otherwise.

reply_to_email_id string · uuid

nullable

The Email ID the draft replies to. null otherwise.

updated_at string · date-time

Timestamp when the draft was last saved.

attachments array of InboxDraftAttachment

The files stored on the draft.

1 field

items InboxDraftAttachment

A file stored on a draft.

4 fields

id string · uuid

The ID of the attachment.

filename string

The filename of the attachment.

content_type string

The MIME type of the attachment.

size integer

The size of the attachment in bytes.

200 Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32",
      "type": "standalone",
      "to": [
        "ada@example.org"
      ],
      "cc": [],
      "bcc": [],
      "subject": "Refund for order 1041",
      "snippet": "Refund issued for order 1041.",
      "thread_id": null,
      "reply_to_email_id": null,
      "updated_at": "2026-08-05T14:12:04.110Z",
      "attachments": [
        {
          "id": "5c1e9d2a-7b3f-4e8a-9c6d-2f0a1b3c4d5e",
          "filename": "receipt.pdf",
          "content_type": "application/pdf",
          "size": 20841
        }
      ]
    }
  ]
}

Example generated from the schema

Create a draft

POST /inboxes/{inbox_id}/drafts

Creates an unsent draft on the inbox. Omit thread_id and reply_to_email_id for a draft that starts a new thread. Pass both together for a reply draft in an existing thread. A reply draft without to is addressed to the sender of the email it replies to, or to its Reply-To when set. For an email the inbox sent, it defaults to that email's to recipients. Send to: [] to leave it empty. At least one of to, cc, bcc, subject, text, html or attachments must be non-empty. The combined recipients of to, cc and bcc cannot exceed 50. Attachments are stored on the draft, so each one needs content, filename and content_type. Returns 201 for a new draft. Only one unsent reply draft can target an email, so a reply draft request for an email that already has one returns 200 with the ID of the existing draft. An unknown thread_id, or a reply_to_email_id that is not in that thread, returns a 404. That request ignores every other field, except attachments, which replaces the attachments of the existing draft when sent. A reply draft created without subject stores an empty subject. When it is sent, it takes the thread subject, prefixed with Re: when it does not already start with it.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

Header parameters

Idempotency-Key string

A unique key for the request, so the draft is created only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the idempotent-replayed: true header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 invalid_idempotency_key. Learn more

rules min length 1max length 256

Request body CreateInboxDraftOptions

At least one of to, cc, bcc, subject, text, html or attachments must be non-empty. The combined recipients of to, cc and bcc cannot exceed 50. thread_id and reply_to_email_id must be sent together or not at all.

to one of

The recipients. For multiple addresses, send an array of strings. Each value can include a friendly name, for example Ada Lovelace <ada@example.org>. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

cc one of

The CC recipients. For multiple addresses, send an array of strings. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

bcc one of

The BCC recipients. For multiple addresses, send an array of strings. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

subject string

nullable

The subject. Max 2000 characters. A string that is only whitespace, or that contains a line break, is rejected.

rules min length 1max length 2000

html string

nullable

The HTML body.

text string

nullable

The plain text body.

attachments array of InboxDraftAttachmentInput

nullable

Files to store on the draft. Each one needs content, filename and content_type. A path without content returns a 422, and when both are sent, path is ignored. A content_id returns a 422. The files on a draft can total at most 25 MB. An empty file or a blocked file type returns a 422.

1 field

items InboxDraftAttachmentInput

A file to store on a draft. Unlike POST /emails attachments, a draft attachment cannot use path or content_id. A path without content returns a 422, and when both are sent, path is ignored.

3 fields

content string

The content of the file, encoded in base64. It cannot be empty.

filename string

The filename of the attachment. A blocked file type returns a 422.

rules min length 1

content_type string

The MIME type of the attachment. It must be a valid MIME type, such as application/pdf, or the request returns a 422.

rules min length 1

thread_id string · uuid

The Thread ID to reply in. Must be sent with reply_to_email_id.

reply_to_email_id string · uuid

The Email ID to reply to, as returned in data[].id by the list thread emails endpoint. Must be sent with thread_id.

Responses

200 201

The reply draft for this email already exists. The response holds the ID of the existing draft, and the request fields other than attachments are not applied.

CreateInboxDraftResponseSuccess

object string

Type of the response object.

id string · uuid

The ID of the draft.

CreateInboxDraftResponseSuccess

object string

Type of the response object.

id string · uuid

The ID of the draft.

POST /inboxes/{inbox_id}/drafts

{
  "to": [
    "ada@example.org"
  ],
  "cc": "string",
  "bcc": "string",
  "subject": "Refund for order 1041",
  "html": "<p>Refund issued for order 1041.</p>",
  "text": "Refund issued for order 1041.",
  "attachments": [
    {
      "content": "aGVsbG8gZTJl",
      "filename": "receipt.pdf",
      "content_type": "application/pdf"
    }
  ],
  "thread_id": "4d8e2a1c-9b3f-4c6d-8a21-3e5f7c9c0d12",
  "reply_to_email_id": "5b1a9f47-2c8d-4e6f-9a03-1d2e3f4a5b60"
}

Example generated from the schema

200 Response

{
  "object": "inbox_draft",
  "id": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32"
}

Example generated from the schema

201 Response

{
  "object": "inbox_draft",
  "id": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32"
}

Example generated from the schema

Retrieve a single draft

GET /inboxes/{inbox_id}/drafts/{draft_id}

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

draft_id string · uuid

The Draft ID.

Responses

200

GetInboxDraftResponseSuccess

object string

The object type.

id string · uuid

The ID of the draft.

type string

reply when the draft replies to an email in an existing thread. standalone when the draft starts a new thread.

enum standalonereply

to array of string

nullable

The recipients. null or empty when no recipients are set.

1 field

items string

cc array of string

The CC recipients.

1 field

items string

bcc array of string

The BCC recipients.

1 field

items string

subject string

nullable

The subject.

html string

nullable

The HTML body.

text string

nullable

The plain text body. A reply draft created without a body has an empty string.

thread_id string · uuid

nullable

The Thread ID when the draft is a reply. null otherwise.

reply_to_email_id string · uuid

nullable

The Email ID the draft replies to. null otherwise.

email_id string · uuid

nullable

The ID of the outbound email queued when the draft was sent. null until the draft is sent.

created_at string · date-time

Timestamp when the draft was created.

updated_at string · date-time

Timestamp when the draft was last saved.

attachments array of InboxDraftAttachment

The files stored on the draft.

1 field

items InboxDraftAttachment

A file stored on a draft.

4 fields

id string · uuid

The ID of the attachment.

filename string

The filename of the attachment.

content_type string

The MIME type of the attachment.

size integer

The size of the attachment in bytes.

200 Response

{
  "object": "inbox_draft",
  "id": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32",
  "type": "standalone",
  "to": [
    "ada@example.org"
  ],
  "cc": [],
  "bcc": [],
  "subject": "Refund for order 1041",
  "html": "<p>Refund issued for order 1041.</p>",
  "text": "Refund issued for order 1041.",
  "thread_id": null,
  "reply_to_email_id": null,
  "email_id": null,
  "created_at": "2026-08-05T14:12:04.110Z",
  "updated_at": "2026-08-05T14:12:04.110Z",
  "attachments": [
    {
      "id": "5c1e9d2a-7b3f-4e8a-9c6d-2f0a1b3c4d5e",
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "size": 20841
    }
  ]
}

Example generated from the schema

Update an existing draft

PATCH /inboxes/{inbox_id}/drafts/{draft_id}

Updates the content of an unsent draft. Omitted fields are left unchanged. Send at least one of to, cc, bcc, subject, text, html or attachments. Sending attachments replaces every attachment on the draft. A request that sets text or html replaces the whole body. The body part you omit from that request becomes null. The merged draft must still contain at least one non-empty field, and its combined recipients cannot exceed 50. A draft that was already sent, or that changed during the request, returns a 409. The response holds only the Draft ID. Retrieve the draft to read its content.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

draft_id string · uuid

The Draft ID.

Request body UpdateInboxDraftOptions

Send at least one of to, cc, bcc, subject, text, html or attachments. Omitted fields are left unchanged. Setting text or html replaces the whole body, so the body part you omit becomes null. The merged draft must contain at least one non-empty field, and its combined recipients cannot exceed 50.

to one of

The recipients. For multiple addresses, send an array of strings. Each value can include a friendly name. Pass null to clear. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

cc one of

The CC recipients. Pass null or [] to clear. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

bcc one of

The BCC recipients. Pass null or [] to clear. Each address is email@example.com or Name <email@example.com>. An address that is not valid returns a 422.

3 fields

one of · 1 string

one of · 2 array of string

rules max items 50

1 field

items string

one of · 3

nullable

subject string

nullable

The subject. Max 2000 characters. Cannot be only whitespace or contain a line break. Pass null to clear.

rules min length 1max length 2000

html string

nullable

The HTML body. Pass null to clear.

text string

nullable

The plain text body. Pass null to clear.

attachments array of InboxDraftAttachmentInput

nullable

1 field

items InboxDraftAttachmentInput

3 fields

content string

The content of the file, encoded in base64. It cannot be empty.

filename string

The filename of the attachment. A blocked file type returns a 422.

rules min length 1

content_type string

The MIME type of the attachment. It must be a valid MIME type, such as application/pdf, or the request returns a 422.

rules min length 1

any of · 1

any of · 2

any of · 3

any of · 4

any of · 5

any of · 6

any of · 7

Responses

200

UpdateInboxDraftResponseSuccess

object string

The object type. Always inbox_draft.

id string · uuid

The ID of the draft.

PATCH /inboxes/{inbox_id}/drafts/{draft_id}

null

Example generated from the schema

200 Response

{
  "object": "inbox_draft",
  "id": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32"
}

Example generated from the schema

Remove an existing draft

DELETE /inboxes/{inbox_id}/drafts/{draft_id}

Discards an unsent draft. A draft that was already sent, or that changed during the request, returns a 409.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

draft_id string · uuid

The Draft ID.

Responses

200

RemoveInboxDraftResponseSuccess

object string

The object type.

id string · uuid

The ID of the draft.

deleted boolean

Indicates whether the draft was successfully deleted.

enum true

200 Response

{
  "object": "inbox_draft",
  "id": "c3a1e8b4-2d5f-4a7c-9e10-6b8d7f5a4c32",
  "deleted": true
}

Example generated from the schema

Send a draft

POST /inboxes/{inbox_id}/drafts/{draft_id}/send

Sends the draft from the inbox address. A reply draft is sent in its thread. A draft without a thread starts a new thread. The draft must have at least one to recipient and html or text, or the request returns a 422. A standalone draft also needs a non-empty subject. A reply draft with an empty subject is sent with the thread subject, prefixed with Re: when it does not already start with it. A draft that was already sent returns a 409. The request body is optional and takes only headers. The whole email, encoded, can be at most 40 MB, or the request returns a 422.

Path parameters

inbox_id string

example "b3e2b2b6-3f0e-4c8e-9ad3-2f43a1e2c7f1"

draft_id string · uuid

The Draft ID.

Header parameters

Idempotency-Key string

A unique key for the request, so the draft is sent only once. A retry with the same key within 24 hours returns the first successful (2xx) response, with the idempotent-replayed: true header. A failed request is not stored, so it can be retried with the same key. Reusing the key with a different body, or while the first request is still running, returns a 409. An empty key, or one longer than 256 characters, returns a 400 invalid_idempotency_key. Learn more

rules min length 1max length 256

Request body SendInboxDraftOptions

headers object

nullable

1 field

additional properties string

Responses

200

SendInboxDraftResponseSuccess

id string · uuid

The ID of the sent email. Use it with the emails endpoints.

POST /inboxes/{inbox_id}/drafts/{draft_id}/send

{
  "headers": {
    "X-Ticket-Id": "4821"
  }
}

Example generated from the schema

200 Response

{
  "id": "6a0c8e58-3d9e-4f7a-8b14-2e3f4a5b6c71"
}

Example generated from the schema