Contacts & properties
A contact is one person in your audience, identified by the contactId you send: use your own id for them rather than an email, if you have one. JourneyKit creates the record the first time it sees the id (in identify or track) and tracks when it first and last saw them. You can also import a list, where a contact without an id takes their email as one.
Each contact has:
- id: your id, exactly as sent. Also available as the
idproperty, so segments, bindings and placeholders can use it like any other. - email and name: set by
identify. The email is where workflow emails go by default; it's also theemailproperty. - properties: a JSON object of everything else
identifysent. Merged shallowly on every call: send only what changed.
Property definitions
Contacts → Properties describes each property key: a label, a type, a description. Definitions do three things, they give segments and workflow bindings readable names, they tell the email editors what's available, and they let an enum property offer its values as choices.
| Type | Meaning |
|---|---|
string | Free text |
enum | One of a fixed list of values (e.g. plan: free, trial, pro). Segment conditions offer these as a dropdown. |
number | |
boolean | |
date | An ISO 8601 string |
object | A nested object; its own fields can be described |
array | A list; each item's fields can be described |
Every workspace starts with three properties: id, name and email. Any other key you send with identify is added as it arrives. id and email are always there and can't be removed. Keys that arrive without a definition show up as Undefined: click one to describe it. Definitions are just descriptions: removing one doesn't delete stored values, and values are stored regardless of type.
Importing a list
Contacts → Import brings in a CSV, a TSV or a pasted list of addresses. Comma, semicolon and tab separators are all recognized. Save a spreadsheet as CSV first. JourneyKit guesses what each column is and shows you every guess, so check them before you import. Any column can become a contact field or be left out.
How an import behaves:
- Matching: a row is matched to an existing contact by id, then by email, so a list of addresses updates the contacts you already have rather than duplicating them. If you plan to install the SDK later, include your own id column: a contact imported with only an email keeps that email as their id, and a later
identifywith a different id creates a second contact. - Merging: values are merged into the contact, or you can choose to leave existing contacts as they are. Empty cells never clear anything.
- Unsubscribes: rows marked as unsubscribed, bounced or similar in a status column go on your unsubscribed list and don't become contacts. Check Everyone in this file has unsubscribed for a separate unsubscribed export. Importing never takes anyone off that list.
- No emails go out: an import doesn't start workflows, including ones triggered by a property change, and doesn't count as activity, so existing contacts keep their last-seen time. New contacts are first seen at their signup date if you map one, otherwise at the time of the import.
- New fields are text: columns stored in a field you've already defined take that field's type. New fields stay text.
Only import people who agreed to hear from you. To import from code, use POST /contacts/import, up to 500 rows per call. It's safe to repeat a call.
Reading properties elsewhere
- Segments: Contact property conditions (
equals,contains,is set, …). - Workflow email steps: bind a preset parameter (or the recipient) to a Contact field,
name,email,externalId, or anyproperties.<key>. - Notify your team steps:
{{name}},{{email}},{{externalId}},{{properties.key}}placeholders in the subject and body.