Mail API reference

Mail API · Contacts

post/v1/workspaces/{workspace_id}/contact-propertiesAuth

Define a contact property

At most 50 per workspace.

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

key*string

The property key: lowercase letters, digits and underscores, starting with a letter, up to 50 characters. Use it as a CSV column header and as a key of `properties` on a contact. Contact fields (`email`, `first_name`, …) are reserved.

Example: "company"

type*enum (2)

Value type. Fixed once created.

fallback_valueobject

The value to use when a contact has none. Must match `type`.

Example: "Acme"

Response · 201

id*string · uuid

The property id.

key*string

The key used in contact `properties` and as `{{key}}` in templates.

Example: "company"

type*object

The value type: `string` or `number`.

fallback_value*object

Value used for a contact that has no value for this property; null for none.

created_at*string · date-time

When the property was created.

updated_at*string · date-time

When the property was last changed.

Example

Request

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

{
  "key": "company",
  "type": "string",
  "fallback_value": "Acme"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "key": "company",
  "type": {},
  "fallback_value": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}