Emails

Retrieve a list of emails

GET /emails

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	Number of items to return.
`after`	`string`	no	Return items after this cursor.
`before`	`string`	no	Return items before this cursor.

Example

curl -X GET "$SESAMESEND_URL/emails" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}

Send an email

POST /emails

Headers

Name	Type	Required	Description
`Idempotency-Key`	`string`	no	A unique identifier for the request to ensure emails are only sent once.

Body

Field	Type	Required	Description
`from`	`string`	yes	Sender email address. To include a friendly name, use the format "Your Name <sender@example.com>".
`to`	`string \| string[]`	yes	Recipient email address. For multiple addresses, send as an array of strings. Max 50.
`subject`	`string`	yes	Email subject.
`bcc`	`string \| string[]`	no	Bcc recipient email address. For multiple addresses, send as an array of strings.
`cc`	`string \| string[]`	no	Cc recipient email address. For multiple addresses, send as an array of strings.
`reply_to`	`string \| string[]`	no	Reply-to email address. For multiple addresses, send as an array of strings.
`html`	`string`	no	The HTML version of the message.
`text`	`string`	no	The plain text version of the message.
`template`	`any`	no	Use a published template to send the email. If provided, do not include html or text.
`template.id`	`string`	yes	The id of the published email template.
`template.variables`	`object`	no	Template variables object with key/value pairs.
`headers`	`object`	no	Custom headers to add to the email.
`scheduled_at`	`string`	no	Schedule email to be sent later. The date should be in ISO 8601 format.
`attachments`	`object[]`	no
`attachments[].content`	`string`	no	Content of an attached file.
`attachments[].filename`	`string`	no	Name of attached file.
`attachments[].path`	`string`	no	Path where the attachment file is hosted
`attachments[].content_type`	`string`	no	Optional content type for the attachment, if not set it will be derived from the filename property
`attachments[].content_id`	`string`	no	Content ID for embedding inline images using cid references (e.g., cid:image001).
`tags`	`object[]`	no
`tags[].name`	`string`	no	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.
`tags[].value`	`string`	no	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`	no	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.

Example

curl -X POST "$SESAMESEND_URL/emails" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "string",
  "to": "string",
  "subject": "string"
}'

Responses

Status	Description
`200`	OK

{
  "id": "string"
}

Retrieve a single email

GET /emails/{email_id}

Path parameters

Name	Type	Required	Description
`email_id`	`string`	yes	The ID of the email.

Example

curl -X GET "$SESAMESEND_URL/emails/<email_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "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"
}

Update a single email

PATCH /emails/{email_id}

Path parameters

Name	Type	Required	Description
`email_id`	`string`	yes	The ID of the email.

Example

curl -X PATCH "$SESAMESEND_URL/emails/<email_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "scheduled_at": "string"
}

Cancel the schedule of the e-mail.

POST /emails/{email_id}/cancel

Path parameters

Name	Type	Required	Description
`email_id`	`string`	yes	The ID of the email.

Example

curl -X POST "$SESAMESEND_URL/emails/<email_id>/cancel" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "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"
}

Create a shareable link for a sent or received email.

POST /emails/{email_id}/share

Path parameters

Name	Type	Required	Description
`email_id`	`string`	yes	The ID of the email.

Body

Field	Type	Required	Description
`expires_in`	`string`	no	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.

Example

curl -X POST "$SESAMESEND_URL/emails/<email_id>/share" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

Status	Description
`200`	OK

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

Trigger up to 100 batch emails at once.

POST /emails/batch

Not yet exercised

This route exists, but it has not yet returned a 2xx response to a real request on the reference instance (see PARITY.md in the repository). Treat its behavior as unverified.

Headers

Name	Type	Required	Description
`Idempotency-Key`	`string`	no	A unique identifier for the request to ensure emails are only sent once.

Example

curl -X POST "$SESAMESEND_URL/emails/batch" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "from": "string",
    "to": "string",
    "subject": "string"
  }
]'

Responses

Status	Description
`200`	OK

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

Retrieve a list of attachments for a sent email

GET /emails/{email_id}/attachments

Path parameters

Name	Type	Required	Description
`email_id`	`string`	yes	The ID of the email.

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	Maximum number of attachments to return.
`after`	`string`	no	Pagination cursor to fetch results after this attachment ID. Cannot be used with 'before'.
`before`	`string`	no	Pagination cursor to fetch results before this attachment ID. Cannot be used with 'after'.

Example

curl -X GET "$SESAMESEND_URL/emails/<email_id>/attachments" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "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
    }
  ]
}

Retrieve a single attachment for a sent email

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

Path parameters

Name	Type	Required	Description
`email_id`	`string`	yes	The ID of the email.
`attachment_id`	`string`	yes	The ID of the attachment.

Example

curl -X GET "$SESAMESEND_URL/emails/<email_id>/attachments/<attachment_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "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
}

Retrieve account-level email metrics

GET /emails/metrics

Query parameters

Name	Type	Required	Description
`start_date`	`string`	no	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`	no	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`	no	The IANA timezone (e.g. `America/New_York`) used to bucket periods when `period` is in `dimensions`.
`granularity`	`"hourly" \| "daily" \| "weekly" \| "monthly"`	no	The bucket size used when `period` is in `dimensions`. The date range can't produce more than 10,000 periods at the chosen granularity.
`metrics`	`"received" \| "delivered" \| "complained" \| "suppressed" \| "bounced" \| "bounced_transient" \| "bounced_permanent" \| "bounced_undetermined" \| "opened" \| "clicked" \| "unsubscribed" \| "delivery_delayed" \| "failed" \| "sent" \| "unique_opened" \| "unique_clicked" \| "delivery_rate" \| "open_rate" \| "click_rate" \| "bounce_rate" \| "complaint_rate" \| "unsubscribe_rate"[]`	no	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.
`dimensions`	`"period" \| "domain" \| "email" \| "broadcast"[]`	no	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.
`domain_id`	`string[]`	no	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.
`email_id`	`string[]`	no	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.
`broadcast_id`	`string[]`	no	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.

Example

curl -X GET "$SESAMESEND_URL/emails/metrics" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "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": {},
  "data": [
    {
      "period": "string",
      "domain_id": "string",
      "domain_name": "string",
      "email_id": "string",
      "broadcast_id": "string",
      "broadcast_name": "string"
    }
  ]
}

Retrieve a list of emailsCopy Anchor Link

Send an emailCopy Anchor Link

Retrieve a single emailCopy Anchor Link

Update a single emailCopy Anchor Link

Cancel the schedule of the e-mail.Copy Anchor Link

Create a shareable link for a sent or received email.Copy Anchor Link

Trigger up to 100 batch emails at once.Copy Anchor Link

Retrieve a list of attachments for a sent emailCopy Anchor Link

Retrieve a single attachment for a sent emailCopy Anchor Link

Retrieve account-level email metricsCopy Anchor Link

On this page

Retrieve a list of emails

Send an email

Retrieve a single email

Update a single email

Cancel the schedule of the e-mail.

Create a shareable link for a sent or received email.

Trigger up to 100 batch emails at once.

Retrieve a list of attachments for a sent email

Retrieve a single attachment for a sent email

Retrieve account-level email metrics