> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Contacts
> Manage individual contacts in your Lettr audience, including their five statuses, custom properties, memberships, and activity history
A contact is one person in your audience, identified by their email address. Every contact belongs to your team, has a single status, an optional set of custom property values, list and topic memberships, and a chronological activity log of changes that have happened to them.
This page covers how to work with individual contacts. For bulk operations like CSV import and export, see [Importing and Exporting](/learn/audience/importing-and-exporting).
## Contact Status
Every contact has exactly one of five statuses. The status determines whether the contact will receive your next campaign and how Lettr handles them internally.
| Status | What it means |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscribed` | Active contact, eligible to receive campaigns. This is the default for newly added contacts. |
| `unsubscribed` | The contact has opted out. Excluded from all campaign sends. |
| `bounced` | A previous email to this address bounced permanently. Excluded from campaigns to protect your sender reputation. |
| `complained` | The contact marked one of your emails as spam. Excluded from campaigns. |
| `unverified` | The contact was created through [double opt-in](/learn/audience/double-opt-in) and hasn't confirmed yet. Excluded from campaigns until they click their confirmation link. |
Only contacts with status `subscribed` are eligible to receive campaigns. Lettr applies this filter automatically when a campaign is sent — you don't need to manage suppression manually.
### Statuses and Your Marketing Plan
Your marketing plan has a contact limit (for example, the free tier allows 500 contacts). The limit is checked against the **total** count of contacts in your audience, regardless of status. Unsubscribed, bounced, and complained contacts still count toward the limit. If your audience exceeds your plan's limit, you cannot send new campaigns until you upgrade your plan or remove contacts.
If you've accumulated a lot of bounced or unsubscribed contacts and you're approaching your plan limit, delete the ones you no longer need before upgrading.
## Adding Contacts
There are three ways to add contacts to your audience:
| Method | Best for | Where to find it |
| ---------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Manual entry** | A handful of contacts you want to add right now | **Audience** → **Contacts** → **Add contacts** |
| **CSV import** | Bringing in a list from another tool | **Audience** → **Imports** → **New import**. See [Importing and Exporting](/learn/audience/importing-and-exporting) |
| **API** | Sign-up forms on your website or app | `POST /api/audience/contacts`, optionally with [double opt-in](/learn/audience/double-opt-in) |
Importing from another system or syncing contacts from your own database? The [Contacts API](/api-reference/audience/bulk-create-contacts) can create or update many contacts in a single request, so you don't have to call the create endpoint once per contact.
### Manual Entry
The **Add contacts** dialog accepts one or more email addresses separated by spaces, commas, or newlines. You can optionally pick a list and a topic to attach the new contacts to in the same step. All new contacts start with status `subscribed`.
Follow an interactive walkthrough of this guide inside Lettr.
### Auto-Attached Topics
Whenever a new contact is created, Lettr automatically attaches every [topic](/learn/audience/topics) whose default is **opt-in**. This means recipients are subscribed to your default topics from the moment they enter your audience, without you having to assign them.
## Editing Contacts
Open any contact from the **Contacts** list to view their profile. From there you can:
* Change their **email address** — the address is unique per team, so an existing email in your audience will block the change
* Change their **status** — useful for manually marking a contact as unsubscribed or re-subscribing them
* Edit their **property values** — covered in the [Custom Properties](#custom-properties) section below
* Add or remove them from **lists** and **topics**
Every change is recorded in the contact's [activity log](#activity-log).
## Deleting Contacts
You can delete contacts individually from their profile, or in bulk from the contacts list (select rows, then use the bulk action bar).
Contact deletion is permanent — there is no recycle bin or recovery. Their activity log, list memberships, and topic memberships are all removed. Past campaign records remain intact, but the contact is no longer linked to them.
If you want to keep a record of a contact but stop emailing them, set their status to `unsubscribed` instead of deleting them.
## Bulk Actions
When you select multiple contacts from the list view, the bulk action bar at the bottom of the page lets you:
* Delete the selected contacts
* Change their status (for example, mass-unsubscribe a set of contacts)
* Add them to or remove them from one or more lists
* Add them to or remove them from one or more topics
Bulk actions are useful after running an import or when cleaning up your audience.
## Custom Properties
Custom properties let you store any data you want on a contact beyond their email and status. You define each property once at the team level (giving it a name and a type), and every contact in your audience can have its own value for it.
Common uses:
* Personalizing campaign emails (`Hi {{first_name}}`)
* Filtering contacts in [segments](/learn/audience/segments) (for example, "all contacts where `plan = pro`")
* Tracking signup-time data you want to keep alongside the contact
### Property Types
Each property has a type that affects how it can be filtered in segments and how it's rendered in the dashboard.
| Type | Use for |
| --------- | ------------------------------------------------------------ |
| `string` | Names, companies, cities, plan tiers, any free-form text |
| `number` | Order counts, revenue, age, any numeric value |
| `boolean` | True/false flags like `is_vip` or `has_completed_onboarding` |
| `date` | Sign-up dates, last purchase dates, renewal dates |
| `json` | Structured data when one of the simple types isn't enough |
### Fallback Values
Each property can have an optional fallback value, used whenever a contact doesn't have a value of their own for that property. Fallbacks are handy when you want to safely personalize emails without leaving variables blank — for example, a `first_name` property with the fallback `there` will render as "Hi there" for contacts whose first name you don't know.
### Managing Properties
Go to **Audience** → **Properties** to view, create, edit, and delete your team's property schema.
Define the properties you care about before you import contacts. The CSV import flow can map columns directly to existing properties, so having them set up first saves a step.
### Using Properties in Campaigns
Custom properties become merge tags in campaign emails. If a contact has a property called `first_name`, you can reference it as `{{first_name}}` in your subject or body. See [Content and Design](/learn/campaigns/content-and-design#personalization) for the full personalization syntax.
## Activity Log
Every contact has a chronological log of events that happened to them. The log is visible on the contact's profile page and includes:
| Event | When it happens |
| ------------------------------------ | ------------------------------------------------------- |
| **Created** | The contact was added to your audience |
| **Subscribed / Unsubscribed** | Their status changed to or from `subscribed` |
| **List added / removed** | They were added to or removed from a list |
| **Topic opted in / opted out** | They subscribed to or unsubscribed from a topic |
| **Property set / changed / cleared** | A custom property value was added, modified, or removed |
| **Email changed** | Their email address was updated |
The activity log is permanent for the life of the contact and is the easiest way to understand why a contact is in their current state.
Contacts added through CSV imports do not generate a "Created" event in the activity log — imports use a faster bulk-insert path that skips per-contact logging. Their list and topic memberships from the import are also not individually logged. All later changes (status, properties, manual list edits) are logged as normal.
## Next Steps
Group contacts into static lists for organization
Let contacts manage their own subscription preferences
Build dynamic groups using contact data and properties
Bulk-load contacts from CSV