Trigger double opt-in confirmations for a list

Trigger double opt-in confirmations for a list

post

https://api.bird.comhttp://localhost:3000https://api.bird.ai

/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.

Authorizations

MessageBird_userMessageBird_accessKey

AuthorizationstringRequired

An access token issued to a user.

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

listIdstring · uuidRequired

Body

application/json

emailChannelIdstring · uuidOptional

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

smsChannelIdstring · uuidOptional

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

rcsChannelIdstring · uuidOptional

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

Responses

200

At least one confirmation was dispatched. See errors for any that were not.

application/json

statusstring · enumRequired

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

Possible values:

confirmationsSentintegerRequired

Number of confirmation messages sent, one per confirmable identifier.

400

The request was malformed.

application/json

404

The requested resource was not found.

application/json

422

The list is not double opt-in, or the request was processed but no identifier could be confirmed (each reason is in errors).

application/json

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

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/double-opt-in/{listId} HTTP/1.1
Host: api.bird.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 219

{
  "identifiers": [
    {
      "key": "emailaddress",
      "value": "text"
    }
  ],
  "emailChannelId": "123e4567-e89b-12d3-a456-426614174000",
  "smsChannelId": "123e4567-e89b-12d3-a456-426614174000",
  "rcsChannelId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "status": "confirmation_pending",
  "confirmationsSent": 1,
  "errors": [
    {
      "key": "text",
      "value": "text",
      "reason": "text"
    }
  ]
}

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

Request

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": "[e-mail]" }],
  "emailChannelId": "7c0a8f12-3b4d-4e5f-9a1b-2c3d4e5f6a7b"
}'

Response (200 OK)

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