Mail API reference

Mail API · Contacts

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

Update a contact

The email cannot change (delete and re-create). Emits `contact.updated` when something changed.

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

first_namestring

New first name; null clears it.

last_namestring

New last name; null clears it.

unsubscribedboolean

Set or clear the global unsubscribe.

propertiesobject

Merged into the stored properties; a `null` value removes that key.

consentobject

Record a consent, or `null` to withdraw it.

Response · 200

id*string · uuid

The contact id.

email*string · email

The contact's email address, unique within the workspace.

Example: "ada@example.com"

first_name*string

The contact's first name.

last_name*string

The contact's last name.

unsubscribed*boolean

Global unsubscribe.

unsubscribed_at*string · date-time

When the contact unsubscribed from all mail; null while subscribed.

properties*object

Custom property values keyed by contact-property key.

Example: {"company":"Acme"}

consented_at*string · date-time

When marketing consent was recorded; null when none was.

consent_source*string

Where the consent to email this contact came from (free text, for your records).

Example: "signup-form-2026"

created_via*object

How the contact was added.

created_at*string · date-time

When the contact was created.

updated_at*string · date-time

When the contact was last changed.

Example

Request

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

{
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "properties": {},
  "consent": {}
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "email": "ada@example.com",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "properties": {
    "company": "Acme"
  },
  "consented_at": "2026-01-01T00:00:00.000Z",
  "consent_source": "signup-form-2026",
  "created_via": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}