# Contacts & CRM

MailTrixy includes a full-featured CRM that stores every person and company you interact with. Contacts are automatically created from incoming and outgoing emails, and enriched with interaction history, custom fields, tags, and lead scores to give your team complete context at every touchpoint.

## Contact Management

The Contacts module provides a centralized directory of every person your workspace has communicated with. Each contact record includes:

- Basic Information: First name, last name, email address (primary and additional), phone number, company, job title, and avatar (auto-fetched from Gravatar when available).
- Address Details: Street address, city, state/province, postal code, and country. Useful for location-based segmentation and compliance (GDPR region tagging).
- Social Profiles: LinkedIn, Twitter/X, Facebook, and website URLs. These are displayed on the contact detail page and can be used in personalization variables.
- Notes: Free-text notes field with rich text support. Team members can add timestamped notes to any contact record.

### Creating Contacts

Contacts can be created in several ways:

- Manual Creation: Click "New Contact" from the Contacts page and fill in the form.
- Auto-Creation from Email: When MailTrixy syncs an email from a new sender, a contact record is automatically created with the sender's name and email address.
- CSV Import: Bulk import contacts from a CSV file (see CSV Import Guide below).
- API: Create contacts programmatically via the REST API.
- Form Submissions: Contacts can be created from embedded web forms or landing page submissions.

## Custom Fields

Extend the contact model with unlimited custom fields to capture data specific to your business:

- Field Types: Text, number, date, dropdown (single-select), multi-select, checkbox, URL, email, phone, and long text.
- Field Configuration: Each custom field has a label, internal key (auto-generated slug), placeholder text, default value, and required/optional flag.
- Field Groups: Organize custom fields into collapsible groups on the contact detail page (e.g., "Subscription Details", "Preferences", "Internal Notes").
- Segmentation: Custom fields can be used as filter criteria when building segments and selecting campaign recipients.
- Personalization: Custom field values are available as merge variables in email templates and campaigns using the `{custom.field_key}` syntax.

## Lead Scoring

MailTrixy assigns a numeric lead score to each contact based on their engagement and profile completeness. The score helps sales teams prioritize outreach by identifying the most engaged and qualified leads.

- Email Engagement: +5 points for opening an email, +10 points for clicking a link, +20 points for replying to an email.
- Website Activity: +15 points for visiting a tracked page, +25 points for submitting a form.
- Profile Completeness: +5 points for each completed profile field (company, phone, address, etc.).
- Recency Decay: Scores decay by 10% every 30 days of inactivity to ensure the score reflects current engagement levels.
- Manual Adjustment: Team members can manually add or subtract points with a reason note.
- Score Thresholds: Configure threshold labels in settings (e.g., 0-25 = Cold, 26-50 = Warm, 51-75 = Hot, 76+ = Qualified). These labels appear as color-coded badges on the contact list.

> Tip: Combine lead scoring with workflow automation to automatically assign high-scoring leads to specific team members or move them to a deal pipeline stage.

## Tags and Segments

### Tags

Tags are free-form labels that can be applied to any contact. They provide a flexible way to categorize contacts beyond the structured fields.

- Apply multiple tags to a single contact.
- Tags are color-coded for visual distinction.
- Bulk-tag contacts by selecting multiple records and choosing "Apply Tag".
- Tags can be applied automatically via workflow actions.

### Segments

Segments are dynamic groups of contacts defined by filter rules. Unlike static lists, segments automatically update as contacts match or stop matching the criteria.

- Filter Criteria: Any combination of standard fields, custom fields, tags, lead score, engagement metrics, creation date, last activity date, and list membership.
- Logical Operators: Combine filters with AND/OR logic. Supports nested groups for complex conditions.
- Real-Time Updates: Segment membership recalculates on each query. No background job needed.
- Use in Campaigns: Segments can be selected as recipient groups when sending campaigns.

## Contact Lists

Lists are static groups of contacts. Unlike segments, list membership is explicitly managed (contacts are manually added or removed, or added via import/workflow).

- Create Lists: Navigate to Contacts > Lists > New List. Give the list a name and optional description.
- Add Contacts: Add contacts individually, in bulk from a CSV, or via workflow automation.
- Subscription Management: Lists support double opt-in. When enabled, contacts receive a confirmation email and must click the link to join the list.
- Unsubscribe Handling: Each campaign sent to a list includes an unsubscribe link. Unsubscribed contacts are marked on the list but their contact record remains intact.

## Contact Merge and Deduplication

Duplicate contacts are common when data flows in from multiple channels. MailTrixy provides tools to detect and merge duplicates:

- Automatic Detection: MailTrixy scans for potential duplicates based on email address (exact match) and name similarity (fuzzy matching (finding approximate matches even with typos or minor differences) using similarity scoring (comparing how closely two names or emails match)). Potential duplicates are flagged in the contact list with a "Possible Duplicate" badge.
- Merge Workflow: Select two or more duplicate contacts and click "Merge". A side-by-side comparison view shows all fields from each record. For each field, choose which value to keep (or combine them). The primary contact retains the merged data, and secondary contacts are soft-deleted.
- Activity Consolidation: When contacts are merged, all emails, notes, tags, deals, and activity history from the secondary contacts are transferred to the primary contact.
- Undo Merge: Merges can be undone within 7 days. The merge operation is logged with a snapshot of the pre-merge state.

## Soft Delete and Trash

Deleting a contact moves it to the trash rather than permanently removing it. This protects against accidental data loss.

- Trash Retention: Contacts remain in trash for 30 days (configurable). After the retention period, they are permanently deleted along with all associated data.
- Restore: Navigate to Contacts > Trash to view and restore deleted contacts. Restoring a contact brings back all their data, tags, and list memberships.
- Permanent Delete: You can permanently delete contacts from the trash immediately if needed. This action cannot be undone.
- Bulk Delete: Select multiple contacts and use the bulk action "Move to Trash" to delete in batch.

## CSV Import Guide

MailTrixy supports batch contact import via CSV files with intelligent field mapping and upsert behavior.

### Import Process

1. Navigate to Contacts > Import and upload your CSV file.
2. MailTrixy reads the CSV headers and displays a column mapping interface. Each CSV column is matched to a MailTrixy contact field (auto-matched by name similarity, with manual override).
3. Choose the import mode:
   - Create Only: Only create new contacts. Skip rows where the email already exists.
   - Update Only: Only update existing contacts. Skip rows where the email does not match an existing contact.
   - Upsert (Create + Update): Create new contacts and update existing ones. The email field is used as the unique key for matching.
4. Optionally assign imported contacts to a list and/or apply tags.
5. Click "Start Import". The import runs as a background queue job, processing rows in batches of 500.
6. A progress indicator shows the import status. When complete, a summary displays the number of created, updated, skipped, and failed records.

### CSV Format Requirements

- UTF-8 encoding (BOM optional).
- Comma-separated values (semicolons and tabs also accepted).
- First row must be column headers.
- Email column is required for matching. Rows without a valid email are skipped.
- Maximum file size: 10 MB (approximately 100,000 rows).
- Date fields should use ISO 8601 format (YYYY-MM-DD) or common formats (MM/DD/YYYY, DD/MM/YYYY) which are auto-detected.

## Cross-Channel Activity Timeline

Every contact detail page features a unified activity timeline that shows all interactions across every channel in chronological order:

- Email Activity: Sent and received emails, opens, clicks, bounces, and replies.
- Campaign Activity: Campaign emails received, opened, clicked, or unsubscribed.
- Deal Activity: Deal stage changes, deal creation, won/lost status.
- Notes: Manually added notes by team members.
- Tag Changes: Tags added or removed, with the team member who made the change.
- WhatsApp/SMS: Messages sent and received via messaging channels (when enabled).
- System Events: Contact created, imported, merged, field updated.

### Timeline Filters

The timeline can be filtered by activity type, date range, and team member. Filters are available as dropdown selectors above the timeline. Multiple activity types can be selected simultaneously.