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.
Corps de la requête
identifiers
array of object
obligatoire
Recipients to confirm. Each is routed to the channel matching its type.
Afficher les paramètres enfants
identifiers.key
string
obligatoire
Identifier type the confirmation is routed by.
Possible values: emailaddress, phonenumber
identifiers.value
string
obligatoire
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.
Corps de la réponse
status
string
obligatoire
No contact was added; confirmations were sent and contacts join on confirmation.
Possible values: confirmation_pending
confirmationsSent
integer
obligatoire
Number of confirmation messages sent, one per confirmable identifier.
errors
array of object
Identifiers that could not be confirmed, each with the reason.
Afficher les attributs enfants
errors.key
string
obligatoire
errors.value
string
obligatoire
errors.reason
string
obligatoire
Exemple de code
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
Exemple de code
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"
}'Exemple de code
{
"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.