PRprivy
Contacts

Unsubscribe a contact

Changed on

Deprecated. Use PATCH /v1/contacts/{id} with email_consent: "unsubscribed" instead. This endpoint will be removed in a future release.

Globally unsubscribe a contact from all email marketing.

If the contact is already unsubscribed, this endpoint returns successfully without making changes.

Responses include Deprecation: true and a Link header pointing to migration documentation.

Required scope: contacts_write

post/contacts/{id}/unsubscribe

Request

  • Base URL
    https://api.privy.com/v1
  • Auth
    HTTP bearer

Path parameters

idstring required

The contact's unique identifier (returned as id in contact responses). Ids are opaque cus_-prefixed strings — a numeric id from a Privy dashboard URL is not a valid API id and will 404; list contacts, or look the contact up by ?email= or ?phone_number=, instead.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Request body

reasonstring

Optional reason for unsubscribing.

Example request

{
  "reason": "Contact requested removal from mailing list"
}

Response

Contact unsubscribed successfully.

Example response

{
  "data": {
    "id": "cus_a1b2c3d4e5f6g7h8",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "email_consent": "subscribed",
    "email_consent_at": "2025-03-20T14:22:00Z",
    "phone_number": "+15551234567",
    "sms_consent": "subscribed",
    "sms_consent_at": "2025-03-20T14:22:00Z",
    "source": "csv",
    "source_type": "import",
    "imported": true,
    "import_ids": [
      "im_k2R5m8Q"
    ],
    "tags": [
      "vip",
      "repeat-buyer"
    ],
    "custom_fields": {
      "loyalty_tier": "gold",
      "referral_code": "JANE2024"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-03-20T14:22:00Z"
  }
}

Changes

  • cf0885e90d5aRevision changes
    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

  • fe500ab59b3bRevision changes
    • info

      endpoint added