Broadcasts

Retrieve a list of broadcasts

GET /broadcasts

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/broadcasts" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

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

Create a broadcast

POST /broadcasts

Body

Field	Type	Required	Description
`name`	`string`	no	Name of the broadcast.
`segment_id`	`string`	yes	Unique identifier of the segment this broadcast will be sent to.
`audience_id`	`string`	no	Use `segment_id` instead. Unique identifier of the segment this broadcast will be sent to.
`from`	`string`	yes	The email address of the sender.
`subject`	`string`	yes	The subject line of the email.
`reply_to`	`string[]`	no	The email addresses to which replies should be sent.
`preview_text`	`string`	no	The preview text of the email.
`html`	`string`	no	The HTML version of the message.
`text`	`string`	no	The plain text version of the message.
`topic_id`	`string`	no	The topic ID that the broadcast will be scoped to.
`send`	`boolean`	no	Whether to send the broadcast immediately or keep it as a draft.
`scheduled_at`	`string`	no	Schedule time to send the broadcast. Can only be used if `send` is true.

Example

curl -X POST "$SESAMESEND_URL/broadcasts" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "segment_id": "string",
  "from": "string",
  "subject": "string",
  "preview_text": "Here are our announcements"
}'

Responses

Status	Description
`201`	OK

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

Retrieve a single broadcast

GET /broadcasts/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Example

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

Responses

Status	Description
`200`	OK

{
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "name": "November announcements",
  "audience_id": null,
  "segment_id": null,
  "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"
}

Update an existing broadcast

PATCH /broadcasts/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Body

Field	Type	Required	Description
`name`	`string`	no	Name of the broadcast.
`audience_id`	`string`	no	Use `segment_id` instead. Unique identifier of the audience this broadcast will be sent to.
`segment_id`	`string`	no	Unique identifier of the segment this broadcast will be sent to.
`from`	`string`	no	The email address of the sender.
`subject`	`string`	no	The subject line of the email.
`reply_to`	`string[]`	no	The email addresses to which replies should be sent.
`preview_text`	`string`	no	The preview text of the email.
`html`	`string`	no	The HTML version of the message.
`text`	`string`	no	The plain text version of the message.
`topic_id`	`string`	no	The topic ID that the broadcast will be scoped to.

Example

curl -X PATCH "$SESAMESEND_URL/broadcasts/<id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

Status	Description
`200`	OK

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

Remove an existing broadcast that is in the draft status

DELETE /broadcasts/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Example

curl -X DELETE "$SESAMESEND_URL/broadcasts/<id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

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

Send or schedule a broadcast

POST /broadcasts/{id}/send

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Body

Field	Type	Required	Description
`scheduled_at`	`string`	no	Schedule email to be sent later. The date should be in ISO 8601 format.

Example

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

Responses

Status	Description
`200`	OK

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

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

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Example

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

Responses

Status	Description
`200`	OK

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

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

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Example

curl -X POST "$SESAMESEND_URL/broadcasts/<id>/duplicate" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`201`	Created

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

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

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

Query parameters

Name	Type	Required	Description
`type`	`"sent" \| "delivered" \| "opened" \| "clicked" \| "bounced" \| "complained" \| "unsubscribed" \| "suppressed"`	yes	The recipient event type to filter by.
`email`	`string`	no	Filter recipients whose email address contains this value.
`bounce_type`	`"permanent" \| "transient" \| "undetermined"`	no	Filter bounced recipients by bounce type. Only valid when `type` is `bounced`.
`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/broadcasts/<id>/recipients" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "b2Zmc2V0OjA",
      "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "ada@example.com",
      "count": 3,
      "bounce_type": "permanent",
      "clicked_links": [
        {}
      ]
    }
  ]
}

Retrieve a broadcast's clicked links

GET /broadcasts/{id}/clicked-links

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Broadcast ID.

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/broadcasts/<id>/clicked-links" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

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

Retrieve a list of broadcasts

Create a broadcast

Retrieve a single broadcast

Update an existing broadcast

Remove an existing broadcast that is in the draft status

Send or schedule a broadcast

Cancel a broadcast

Duplicate a broadcast

Retrieve broadcast recipients

Retrieve a broadcast's clicked links

On this page

Broadcasts

Retrieve a list of broadcastsCopy Anchor Link

Create a broadcastCopy Anchor Link

Retrieve a single broadcastCopy Anchor Link

Update an existing broadcastCopy Anchor Link

Remove an existing broadcast that is in the draft statusCopy Anchor Link

Send or schedule a broadcastCopy Anchor Link

Cancel a broadcastCopy Anchor Link

Duplicate a broadcastCopy Anchor Link

Retrieve broadcast recipientsCopy Anchor Link

Retrieve a broadcast's clicked linksCopy Anchor Link

On this page

Retrieve a list of broadcasts

Create a broadcast

Retrieve a single broadcast

Update an existing broadcast

Remove an existing broadcast that is in the draft status

Send or schedule a broadcast

Cancel a broadcast

Duplicate a broadcast

Retrieve broadcast recipients

Retrieve a broadcast's clicked links