108 lines
2.0 KiB
Plaintext
108 lines
2.0 KiB
Plaintext
---
|
|
title: Contacts
|
|
description: Store and manage your audience
|
|
icon: Users
|
|
---
|
|
|
|
## Structure
|
|
|
|
```json
|
|
{
|
|
"id": "contact_abc123",
|
|
"email": "[email protected]",
|
|
"subscribed": true,
|
|
"data": {
|
|
"firstName": "Sarah",
|
|
"plan": "pro",
|
|
"mrr": 99
|
|
}
|
|
}
|
|
```
|
|
|
|
## Adding contacts
|
|
|
|
- **Dashboard:** Contacts → Add Contact
|
|
- **CSV import:** Contacts → Import
|
|
- **API:** `POST /contacts`
|
|
- **Events:** Auto-created when tracking events
|
|
|
|
## Contact data
|
|
|
|
The `data` field stores custom key-value pairs.
|
|
|
|
**Best practices:**
|
|
- Use consistent naming (camelCase or snake_case)
|
|
- Store dates as ISO strings: `"2024-03-15T10:30:00Z"`
|
|
- Use numbers for numeric values (enables comparisons)
|
|
|
|
## Localization
|
|
|
|
The `locale` field in contact data overrides the project-wide language setting for that specific contact.
|
|
|
|
**Where it's used:**
|
|
- Unsubscribe and preference center pages
|
|
- Email footer translations
|
|
- All contact-facing content
|
|
|
|
**Example:**
|
|
|
|
```javascript
|
|
// Set a contact's preferred language
|
|
POST /contacts
|
|
{
|
|
"email": "[email protected]",
|
|
"data": {
|
|
"locale": "de" // German
|
|
}
|
|
}
|
|
```
|
|
|
|
**Via tracking:**
|
|
|
|
```javascript
|
|
POST /v1/track
|
|
{
|
|
"event": "signup",
|
|
"email": "[email protected]",
|
|
"data": {
|
|
"locale": "fr" // French
|
|
}
|
|
}
|
|
```
|
|
|
|
**Behavior:**
|
|
- If `locale` is set: uses contact's language
|
|
- If not set: uses project's default language
|
|
- Falls back to English if neither is set
|
|
|
|
## Template variables
|
|
|
|
Use `{{fieldName}}` in emails:
|
|
|
|
```html
|
|
<p>Hello {{firstName}}!</p>
|
|
```
|
|
|
|
**Fallback:** `{{firstName ?? 'there'}}`
|
|
|
|
**System-generated fields (always available):**
|
|
- `{{email}}` - Contact's email address
|
|
- `{{unsubscribeUrl}}` - Link to unsubscribe page
|
|
- `{{subscribeUrl}}` - Link to subscribe page
|
|
- `{{manageUrl}}` - Link to preference center
|
|
|
|
**Special fields:**
|
|
- `{{locale}}` - Contact's language preference (user-settable, overrides project default)
|
|
|
|
## Temporary data
|
|
|
|
Data that won't save to contact:
|
|
|
|
```javascript
|
|
data: {
|
|
resetCode: { value: 'ABC123', persistent: false }
|
|
}
|
|
```
|
|
|
|
Use for: one-time codes, tokens, session data.
|