Trigger double opt-in confirmations for a list

POST

/workspaces/{workspaceId}/double-opt-in/{listId}

Sends a double opt-in confirmation message for each identifier instead of adding the contacts to the list. The target list must be double opt-in. Each identifier is routed to the channel matching its type, and each contact joins the list only after it clicks the confirmation link. If no identifier could be confirmed, the request returns 422.

Payload permintaan

identifiers

array of object

wajib

Recipients to confirm. Each is routed to the channel matching its type.

Tampilkan parameter turunan

identifiers.key

string

wajib

Identifier type the confirmation is routed by.

Possible values: emailaddress, phonenumber

identifiers.value

string

wajib

The email address or phone number to send the confirmation to.

emailChannelId

string

Active email-sparkpost channel used to confirm emailaddress identifiers. Required when any emailaddress identifier is present.

smsChannelId

string

Active sms-messagebird channel used to confirm phonenumber identifiers. Provide exactly one of smsChannelId or rcsChannelId when any phonenumber identifier is present.

rcsChannelId

string

Active rcs-google channel used to confirm phonenumber identifiers. Provide exactly one of smsChannelId or rcsChannelId when any phonenumber identifier is present.

Payload respons

status

string

wajib

No contact was added; confirmations were sent and contacts join on confirmation.

Possible values: confirmation_pending

confirmationsSent

integer

wajib

Number of confirmation messages sent, one per confirmable identifier.

errors

array of object

Identifiers that could not be confirmed, each with the reason.

Tampilkan atribut turunan

errors.key

string

wajib

errors.value

string

wajib

errors.reason

string

wajib

Contoh kode

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/double-opt-in/{listId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Examples

The target list must be double opt-in. Instead of adding the contacts directly, this sends a confirmation message per identifier — each contact joins the list only after it clicks the confirmation link. Each identifier is routed to the channel matching its type: an email address to emailChannelId, a phone number to exactly one of smsChannelId or rcsChannelId.

Example data used below:

Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352
List ID (double opt-in): 123e4567-e89b-12d3-a456-426614174000
Email channel ID (active): 7c0a8f12-3b4d-4e5f-9a1b-2c3d4e5f6a7b
AccessKey: abcd

Trigger a confirmation for an email address

Contoh kode

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/double-opt-in/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "identifiers": [{ "key": "emailaddress", "value": "test@example.com" }],
  "emailChannelId": "7c0a8f12-3b4d-4e5f-9a1b-2c3d4e5f6a7b"
}'

Contoh kode

{
  "status": "confirmation_pending",
  "confirmationsSent": 1
}

The response status is always confirmation_pending: no contact is added yet. confirmationsSent counts the identifiers a confirmation was dispatched for. Any identifier that could not be confirmed is returned under errors with a per-identifier reason; if none could be confirmed, the request returns 422.