Delete a preference
/v1/preferences/{preference_id}const result = await bird.preferences.delete("prf_01krdgeqcxet5s7t44vh8rt9mg");
if (!result.applied) {
console.log("refused — a newer statement survived:", result.preference?.status);
}result = client.preferences.delete("prf_01krdgeqcxet5s7t44vh8rt9mg")
if not result.applied and result.preference:
print("refused, current statement:", result.preference.status)result, err := client.Preferences.Delete(context.Background(), "prf_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
log.Fatal(err)
}
// A newer statement recorded since refuses the delete: Applied comes back
// false and Preference carries the statement that survived.
switch {
case result.Applied == nil:
case !*result.Applied && result.Preference != nil:
fmt.Println("delete refused, surviving statement:", result.Preference.Id)
default:
fmt.Println("deleted")
}// applied:false means a newer statement survived the request; the surviving
// record comes back on the result rather than being deleted out from under it.
$result = $bird->preferences->delete('prf_01krdgeqcxet5s7t44vh8rt9mg');
if ($result->getApplied() === false) {
$survivor = $result->getPreference();
echo 'refused: ', $survivor?->getStatus();
}bird preferences delete <preference-id> --yescurl -X DELETE "https://us1.platform.bird.com/v1/preferences/{preference_id}" \
-H "Authorization: Bearer $TOKEN"{
"transition_id": "prt_01krdgeqcxet5s7t44vh8rt9mg",
"preference": {
"id": "prf_01krdgeqcxet5s7t44vh8rt9mg",
"channel": "sms",
"handle": "+15550001234",
"sender_scope": "+15557654321",
"topic_id": null,
"status": "revoked",
"coverage": "non_transactional",
"origin": "api_key",
"source": "signup-form-v2",
"contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
"complaint_message_id": null,
"brand_id": null,
"created_at": "2026-05-20T09:14:52Z",
"updated_at": "2026-05-25T16:42:01Z"
}
}
Deletes a preference, returning its key to having no record, as if nothing had ever been stated. The deletion itself is kept on the key's history, so a later statement is still ordered against what was deleted.
Person-stated opt-outs and active email Brand complaints cannot be deleted. Attempts return 422 E25005. To record renewed consent, use the individual POST /v1/preferences operation with status: granted and consented_at strictly later than the opt-out or complaint. Bulk writes and imports cannot clear complaints. Other applicable opt-outs and delivery blocks still apply.
A delete is ordered like any statement, using the time it is received: if the record carries a statement made after that moment, the delete is refused and returned with applied: false alongside the surviving record. An ID that does not exist in the workspace returns 404.
Parameters
preference_idstringID of the preference, as returned when it was recorded or listed. The ID stays stable while the key holds a record; deleting and re-recording the same key mints a new one.
Response Payload
appliedWhether the request took effect. False when causal ordering or protected complaint rules refuse the request; the surviving statement is returned in preference. A grant returns false when a newer opt-out or deletion survives, even if its consent history is retained.
transition_idIdentifies this write on the key's record, for applied and refused requests alike. Null when the write was a repeat of the current statement and recorded nothing new.
preferenceThe key's surviving statement. Null after an applied delete, when the key is back to having no record. It is also null after a refused grant when a later deletion remains in force.
Show child attributes
preference.idpreference.channelThe channel a preference statement applies to. A preference addresses one channel: the handle that identifies the person differs per channel, so opting out of one channel says nothing about the others. New channels can be added over time, so a value outside this list can be returned.
Possible values (may grow over time): email, sms, whatsapp, amb
preference.handleWho the statement is about: an email address on the email channel, a phone number in E.164 format on SMS, WhatsApp, and Apple Messages for Business.
preference.sender_scopeThe sender the statement is limited to, or null when it covers the whole channel. On SMS this is the originator the person replied to; on WhatsApp it identifies the business account that messaged them; on Apple Messages for Business it is the Apple business ID used for invitations. Email preferences use brand_id instead, so sender_scope is always null there.
preference.topic_idThe topic the statement is limited to, or null when it covers every topic. Part of the key that identifies a statement, alongside sender_scope.
preference.statusWhat the statement says: granted records consent to receive messages, revoked records an opt-out. There is no third state: a person who never stated anything simply has no preference on record.
Possible values: granted, revoked
preference.coverageHow much traffic the statement covers. non_transactional covers marketing and other non-essential messages while transactional messages such as receipts and verification codes keep flowing; all covers every message including transactional ones. Apple Messages for Business phone invitations have no transactional exemption, so either value covers them.
Possible values: all, non_transactional
preference.effective_atWhen the statement was made, as reported by whoever made it. This is what orders one key's statements: a write dated before this moment is refused rather than applied.
preference.originHow the statement was made. Statements the person made themselves (unsubscribe_link, unsubscribe_event, keyword, preference_page, complaint) carry more weight than ones asserted on their behalf (api_key, user, import): deletion cannot remove a person's own opt-out. A Brand complaint can be cleared only by a newer opt-in through the individual-recipient preference operation. New origins can be added over time, so a value outside this list can be returned.
Possible values (may grow over time): unsubscribe_link, unsubscribe_event, keyword, preference_page, api_key, user, import, complaint
preference.sourceFree-form note on where the statement came from, as supplied when it was recorded: a form name, an import batch, a campaign. Null when none was given.
preference.consented_atWhen the person consented, as evidenced by whoever asserted the grant. Null on statements that carry no consent evidence, including every opt-out.
preference.contact_idThe contact whose handle matched when the statement was recorded. Null when no contact matched at that moment; it is not updated when contacts change later.
preference.complaint_message_idThe email that caused the most recent recorded spam complaint for this preference. Null when no complaint is recorded. Retained after a newer individual opt-in clears complaint protection; check status and origin for the current preference.
preference.brand_idThe business this email preference belongs to.
preference.created_atpreference.updated_atRelated resources
Continue with the documentation, guides and examples for this topic.