Mail API reference

Mail API · Contacts

patch/v1/workspaces/{workspace_id}/contacts/{contact}/topicsAuth

Opt a contact in to or out of topics

Records the contact's choice per topic (an explicit `opt_in` is consent for that topic). A global unsubscribe still wins: clear it with `PATCH .../contacts/{contact}` `unsubscribed: false`. Emits `contact.updated`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

contact*string

The contact id, or its email address (URL-encoded).

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

topics*array

The topics to change, each with its new subscription.

Response · 200

contact_id*string · uuid

The contact these subscriptions belong to.

data*array

Every topic of the workspace with this contact's subscription to it.

Example

Request

PATCH https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/contacts/{contact}/topics
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "topics": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "subscription": "opt_in"
    }
  ]
}

Response

{
  "contact_id": "00000000-0000-0000-0000-000000000000",
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "description": "string",
      "default_subscription": {},
      "visibility": {},
      "subscription": {},
      "subscribed": false,
      "reason": {}
    }
  ]
}