Docs/Contacts & Audiences/Managing Contacts

Managing Contacts

Contacts are the foundation of every campaign. Learn how to add and import contacts, use custom fields for rich personalization, understand contact statuses, and keep your list clean with suppression management.

Contact Data Model

Every contact in EmailSendX is associated with a workspace and has a set of core properties plus any custom fields you define. Here's the full shape of a contact object:

json

{
  "id": "cnt_01hx4kpqr9vze8w3t5n2m7b6f",
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "status": "active",
  "tags": ["newsletter", "trial-user"],
  "metadata": {
    "source": "website-signup",
    "signup_page": "/pricing"
  },
  "custom": {
    "company": "Acme Corp",
    "plan": "pro",
    "renewal_date": "2026-12-01"
  },
  "lists": [
    {
      "id": "lst_02jy5lqrs0waf9x4u6o3n8c7g",
      "name": "Newsletter Subscribers"
    }
  ],
  "created_at": "2025-03-15T09:22:00Z",
  "updated_at": "2026-04-01T14:05:33Z",
  "last_emailed_at": "2026-04-10T08:00:00Z"
}

Key properties:

email — unique identifier within a workspace. Required. Cannot be changed once set.
status — one of active, unsubscribed, bounced, or complained. Controls whether the contact receives campaigns.
tags — array of string labels. Used for filtering and automation triggers.
metadata — free-form key-value pairs. Not available in templates. Useful for internal tracking.
custom — workspace-defined typed fields. Available in email templates as {{custom.field_name}}.

Adding Contacts

There are three ways to add contacts to a workspace:

1. Manual add via dashboard

Go to Contacts → Add Contact. Fill in the email address and any other fields. This is best for adding one-off test contacts or specific individuals.

2. API

Use the POST /contacts endpoint to create or update contacts programmatically. This is the standard method for syncing contacts from your app or CRM.

bash

curl -X POST https://emailsendx.com/api/v1/contacts \
  -H "Authorization: Bearer esx_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "tags": ["trial-user"],
    "custom": {
      "company": "Acme Corp",
      "plan": "pro"
    },
    "list_ids": ["lst_02jy5lqrs0waf9x4u6o3n8c7g"]
  }'

If a contact with the given email already exists, the API updates their record (upsert behavior). Pass "merge_tags": true to append tags rather than replace them.

3. CSV import

See the CSV Import section below.

CSV Import

CSV import is the fastest way to bring a large existing list into EmailSendX. Go to Contacts → Import → Upload CSV.

Import steps

Upload your file: Drag and drop or click to upload. Supported formats: .csv, .tsv. Max file size: 100 MB (about 1 million rows). Larger files should be split.
Map columns: EmailSendX shows your CSV headers on the left. Map each header to the corresponding EmailSendX field on the right. The email column is required. Unmapped columns can be imported as new custom fields.
Configure import options:
- Duplicate handling: Skip existing contacts, update them, or merge tags.
- Add to list: Optionally assign all imported contacts to an existing list.
- Apply tags: Add one or more tags to all contacts in this import.
- Status: Import as Active (default) or treat as suppression import.
Review and start: EmailSendX shows a preview of the first 5 rows with your mapping applied. Click Start Import.

Imports run in the background. You'll receive an email summary when complete, showing how many contacts were created, updated, skipped, and if any rows had errors (invalid email format, etc.).

Minimum required column

Your CSV must have an email column. EmailSendX will reject rows with missing or malformed email addresses and report them in the import summary.

Custom Fields

Custom fields let you store structured, typed data on contacts beyond the built-in properties. They're defined at the workspace level and apply to all contacts.

Creating custom fields

Go to Workspace Settings → Custom Fields → Add Field. Each field needs:

Label: human-readable name (e.g., "Company Name")
Slug: auto-generated snake_case identifier used in templates and API (e.g., company_name)
Type: Text, Number, Date, Boolean
Default value: optional fallback when the field is empty

Using custom fields in templates

Reference custom fields in email subject lines and body using the custom. prefix:

{{custom.company_name}} — text field
{{custom.renewal_date}} — date field
{{custom.monthly_spend | default:"0"}} — with fallback

See Merge Tags for the full template syntax reference.

Contact Statuses

Every contact has a status that determines whether they receive campaign emails:

Status	Meaning	How it's set
active	Eligible to receive campaigns. This is the default status for new contacts.	Default on create. Can be set via API or import.
unsubscribed	Opted out. Will not receive any campaign emails. Respects all one-click unsubscribes and manual opt-outs.	Contact clicks unsubscribe link. Admin can set manually. API can set.
bounced	Hard bounce — the email address is invalid or the mailbox doesn't exist. Excluded from all future sends.	Automatically set by EmailSendX when provider reports a hard bounce.
complained	Spam complaint — the contact marked an email as spam. Excluded from all future sends to protect sender reputation.	Automatically set when provider's FBL (feedback loop) reports a complaint.

Status changes are permanent for bounces and complaints

A hard-bounced or complained contact will not be automatically re-subscribed even if their email starts working again. You can manually change status via the contact profile or API, but do so with caution — repeatedly sending to bounced addresses harms your domain reputation. Only re-activate a bounced contact if you have strong reason to believe the address is now valid (e.g., the person contacted you directly with a correction).

Suppression Lists

The suppression list is a workspace-level blocklist. Any email address on the suppression list will never receive emails from this workspace, regardless of their contact status or list membership.

How suppression works

Automatic suppression: hard bounces and spam complaints are added to the suppression list automatically. The underlying contact is also marked bounced or complained.
Manual suppression: add individual addresses or upload a suppression CSV via Contacts → Suppression List → Add.
Migrating suppressions: if switching from another platform, export your suppression/bounce list and import it into EmailSendX before sending your first campaign. This prevents re-sending to addresses that already bounced or complained on your old platform.
Cross-workspace suppression: on Pro and Business plans, you can enable account-level suppression that applies across all workspaces. When a contact unsubscribes in one workspace, they're suppressed in all others. Useful for agencies that manage multiple brands for the same end users.

Manage suppressions from Contacts → Suppression List in the dashboard. Programmatic suppression via the public API is not yet exposed — for now, all suppression actions go through the UI.

Build and manage your audience

Import contacts, define custom fields, and keep your list healthy with automatic bounce and complaint handling.

Go to Contacts Explore the API

Managing Contacts

Contact Data Model#

Adding Contacts#