Managing Contacts
Contacts in Synapse are automatically created and updated when your application sends events. This page covers how to find, view, and understand your contacts in the dashboard.
Browsing Contacts
Go to Contacts in the dashboard sidebar to see your full contact list. The list shows:
| Column | Description |
|---|---|
| The contact's email address | |
| Name | First and last name (if available) |
| Product Type | The product category associated with this contact |
| Status | Subscription status (subscribed, unsubscribed, complained) |
| Created | When the contact was first added to Synapse |
| Last Event | When the most recent event was received for this contact |
Searching and Filtering
Search
Use the search bar to find contacts by:
- Email address
- First or last name
- External ID (the user ID from your application)
Filters
Click Filter to narrow the list by:
| Filter | Description |
|---|---|
| Subscription Status | Show only subscribed, unsubscribed, or complained contacts |
| Product Type | Filter by product category |
| Date Created | Show contacts created within a date range |
| Has Property | Filter contacts that have (or don't have) a specific custom property |
You can combine multiple filters. All filters use AND logic -- contacts must match every active filter.
Contact Detail Page
Click on any contact to see their full profile. The detail page has several sections:
Profile Overview
Shows the contact's core information:
- Email, name, phone number
- External ID (how your application identifies this person)
- Product type and subscription status
- Account creation date
Custom Properties
A table of all custom properties stored on this contact. Properties come from event data and are stored as key-value pairs. Common examples:
- Country, language, timezone
- Plan or subscription tier
- Tags set by flows (e.g.,
onboarding_status: completed)
Event Timeline
A chronological list of all events received for this contact, newest first. Each event shows:
| Field | Description |
|---|---|
| Event Name | The type of event (e.g., user_signup, order_placed) |
| Date | When the event occurred |
| Attributes | The data that came with the event (expandable) |
The event timeline is invaluable for debugging. If a flow didn't trigger as expected, check the timeline to confirm the event was received and see what data it included.
Email History
A list of all emails sent to (or attempted for) this contact:
| Field | Description |
|---|---|
| Template | Which email template was used |
| Flow | Which flow sent the email (if applicable) |
| Status | Current delivery status (sent, delivered, opened, clicked, bounced, suppressed) |
| Sent At | When the email was sent |
| Opened At | When the email was first opened (if applicable) |
| Clicked At | When a link was first clicked (if applicable) |
How Contacts Are Created
Contacts are created automatically when your application sends an event to Synapse:
- Your application sends an event with a
user_id(external ID). - Synapse looks for an existing contact with that external ID.
- If found, the contact's properties are updated with any new data from the event.
- If not found, a new contact is created using the event data.
This means you don't need to manually create contacts. Your application's events keep the contact database up to date automatically.
Contacts can also include override data sent with each event. For example, if a contact changes their email address, including the new email in the event's contact overrides will update the contact record.
Subscription Status
Each contact has a subscription status that affects whether they receive emails:
| Status | Meaning | Emails Sent? |
|---|---|---|
| Subscribed | Contact is opted in to receive emails | Yes |
| Unsubscribed | Contact has opted out or was hard-bounced | No |
| Complained | Contact marked an email as spam | No |
Subscription status changes happen automatically:
- A hard bounce sets the contact to
unsubscribed - A spam complaint from the email provider sets the contact to
complained - Your application can also update the status via event data
Synapse will never send emails to contacts with unsubscribed or complained status. This is a safety measure to protect your sender reputation and comply with email regulations.
Role-Based Access
Not all team members can see the same contact data:
| Role | Can View Contact List | Can Edit Contacts |
|---|---|---|
| Owner | Yes | Yes |
| Admin | Yes | Yes |
| Developer | Yes | No |
| Marketing | Yes | No |
| Operations | Yes | No |
| Viewer | No | No |
See Team Roles & Permissions for the full permission matrix.
Saved Views
Saved views let you store filter and column configurations so you can quickly switch between different ways of looking at your contacts. For example, you might create views for "Active subscribers", "Unsubscribed contacts", or "Contacts in Singapore".
Creating a View
- Set up the filters and columns you want in the contact list.
- Click Save View.
- Give the view a name.
- Optionally set it as the default view (loaded when you open Contacts).
- Optionally pin it for quick access from the view switcher.
Managing Views
- Edit: Click the view name in the view switcher, then update the name, filters, columns, or sort order.
- Delete: Open the view menu and select Delete. System views (e.g., "All Contacts") cannot be deleted.
- Set as Default: Mark a view as the default so it loads automatically when you open the Contacts page.
- Pin: Pin frequently-used views to the top of the view switcher. Pinned views appear in pin-order first, then the rest sorted by creation date.
Each workspace can have up to 20 custom saved views. System views (like "All Contacts") do not count toward this limit and cannot be modified or deleted.
Bulk Actions
When you need to make changes to many contacts at once, use bulk actions instead of editing contacts one at a time.
How to Use Bulk Actions
- Select contacts using the checkboxes in the contact list, or use Select All to target all contacts matching your current filters.
- Click Actions in the toolbar.
- Choose an action:
| Action | Description |
|---|---|
| Delete | Permanently remove the selected contacts |
| Update Status | Change subscription status (subscribed, unsubscribed, bounced, complained) |
| Export | Export the selected contacts as CSV or JSON |
Selection Modes
- Individual selection: Check the boxes next to specific contacts (up to 200 at a time).
- Select All: Applies the action to all contacts matching your current filters -- even those on other pages. Use this for large-scale operations.
Bulk delete is permanent and cannot be undone. Double-check your selection before confirming.
Exporting Contacts
You can export your contacts as CSV or JSON files for use in external tools, reporting, or backups.
How to Export
- Go to Contacts in the sidebar.
- Optionally apply filters to narrow the export scope.
- Click Export in the toolbar.
- Choose the file format (CSV or JSON).
- Select which columns to include, or leave blank for all columns.
Export Behavior
| Contact Count | Behavior |
|---|---|
| 5,000 or fewer | File downloads immediately as a streaming response |
| More than 5,000 | Export runs as a background job -- you will receive a notification when the file is ready to download |
For large exports, you can check the status in Settings > Jobs or poll the Jobs API (GET /v1/jobs/{job_id}). Completed export files are available for download for 24 hours.
Export Scope Options
| Scope | Description |
|---|---|
| All | Export all contacts in your workspace |
| Filtered | Export only contacts matching your current filters |
| Selected | Export only the contacts you have checked |
Use the include_properties option to flatten custom properties into individual columns in your CSV. This makes the export easier to work with in spreadsheet applications.
Property and Event Discovery
The Contacts page includes tools to explore what data exists across your contact base, useful for building filters and segments.
Browsing Property Keys
Click Properties in the filter builder to see a list of all custom property keys found across your contacts. Each key shows:
- The key name (e.g.,
country,plan,signup_source) - How many contacts have that property set
- The auto-detected data type (string, number, boolean, or date)
Browsing Property Values
After selecting a property key, you can see the distinct values for that key. For example, selecting the country key might show SG (342 contacts), US (215 contacts), VN (89 contacts). This helps you pick the right filter values.
Browsing Event Names
The event name browser shows all distinct event names received in your workspace, with counts. You can filter by event source (API, Resend, system, flow) to narrow the list. This is useful when setting up flow triggers or segment conditions based on event behavior.