/v1/workspaces/{workspace_id}/contacts/{contact}AuthUpdate a contact
The email cannot change (delete and re-create). Emits `contact.updated` when something changed.
Path parameters
workspace_id*string · uuidId of the workspace.
contact*stringThe contact id, or its email address (URL-encoded).
Headers
Idempotency-KeystringOpaque 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_namestringNew first name; null clears it.
last_namestringNew last name; null clears it.
unsubscribedbooleanSet or clear the global unsubscribe.
propertiesobjectMerged into the stored properties; a `null` value removes that key.
consentobjectRecord a consent, or `null` to withdraw it.
Response · 200
id*string · uuidThe contact id.
email*string · emailThe contact's email address, unique within the workspace.
Example: "ada@example.com"
first_name*stringThe contact's first name.
last_name*stringThe contact's last name.
unsubscribed*booleanGlobal unsubscribe.
unsubscribed_at*string · date-timeWhen the contact unsubscribed from all mail; null while subscribed.
properties*objectCustom property values keyed by contact-property key.
Example: {"company":"Acme"}
consented_at*string · date-timeWhen marketing consent was recorded; null when none was.
consent_source*stringWhere the consent to email this contact came from (free text, for your records).
Example: "signup-form-2026"
created_via*objectHow the contact was added.
created_at*string · date-timeWhen the contact was created.
updated_at*string · date-timeWhen 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"
}