Add or update email-list members

POST https://api.dairo.app/v1/audiences/{audienceId}/members

Adds or updates members on a list in one batch and returns { "audienceId", "imported" }, where imported is the number of members submitted. Each entry in members is either a raw handle (a plain email address, normalized) or a contactId whose address is resolved from that contact's primary email handle — supplying both, or neither, is a 400; an unknown or cross-project contact is a 404, and a contact with no email handle is a 422. Optional per-member name and metadata (defaulting to {}) are stored on the row. Members merge on the (list, address) pair, so re-adding an existing address updates it in place instead of creating a duplicate, which makes retries safe. At most 2000 members may be sent per request (413 above that; an empty array is a 400). Requires the audiences:write scope.

Scope: audiences:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/audiences/3fa85f64-5717-4562-b3fc-2c963f66afa6/members" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      {
        "email": "person@example.com",
        "contactId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Ada Lovelace",
        "metadata": {}
      }
    ]
  }'

Path parameters

Body

Required, application/json: AudienceMembersRequest.

Response

200 Success. Body: application/json, AudienceMembersResponse.

{
  "audienceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "imported": 0
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.