Mail API reference

Mail API · Contacts

post/v1/workspaces/{workspace_id}/contactsAuth

Create a contact

Emits `contact.created`. Without `consent`, the contact receives only topics it is explicitly opted in to.

Path parameters

workspace_id*string · uuid

Id of the workspace.

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

email*string · email

Unique per workspace; stored lowercased.

Example: "ada@example.com"

first_namestring

The contact's first name, available as `{{first_name}}` in templates.

Example: "Ada"

last_namestring

The contact's last name, available as `{{last_name}}` in templates.

Example: "Lovelace"

unsubscribedboolean

Global unsubscribe: the contact receives no topic mail and no mail with an unsubscribe link. Transactional mail is unaffected.

propertiesobject

Custom properties, keyed by a defined contact property (`POST /contact-properties`). Values must match its type.

Example: {"company":"Acme","seats":12}

consentobject

A marketing consent the contact gave you. Without one, the contact receives only topics it explicitly opted in to (`topics`, or `PATCH .../topics`).

topicsarray

Initial topic subscriptions.

Response · 201

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

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

{
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "unsubscribed": false,
  "properties": {
    "company": "Acme",
    "seats": 12
  },
  "consent": {},
  "topics": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "subscription": "opt_in"
    }
  ]
}

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"
}