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.

Verzoek-payload

identifiers

array of object

verplicht

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

Onderliggende parameters tonen

identifiers.key

string

verplicht

Identifier type the confirmation is routed by.

Possible values: emailaddress, phonenumber

identifiers.value

string

verplicht

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.

Antwoord-payload

status

string

verplicht

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

Possible values: confirmation_pending

confirmationsSent

integer

verplicht

Number of confirmation messages sent, one per confirmable identifier.

errors

array of object

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

Onderliggende attributen tonen

errors.key

string

verplicht

errors.value

string

verplicht

errors.reason

string

verplicht

Codevoorbeeld

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

Codevoorbeeld

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

Codevoorbeeld

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