Managing Contacts

Contacts are the email addresses you send campaigns to. This page covers importing via CSV, custom fields, dynamic segments, exporting, and managing your suppression list.

Importing contacts via CSV

Go to Contacts → Import CSV and upload your file. The import runs in the background for large lists — you'll see a progress indicator and receive an in-app notification when complete.

Required columns

Your CSV must include at least an email column. The header can be any of: email, Email, EMAIL, email_address, or Email Address.

Recommended CSV structure

email,first_name,last_name,company,plan,subscribed_at
ada@example.com,Ada,Lovelace,Babbage Co,pro,2026-01-15
grace@example.com,Grace,Hopper,Navy Labs,free,2026-02-01
alan@example.com,Alan,Turing,Princeton,pro,2026-01-28

Column mapping

After uploading, SES Mailbox shows a mapping screen where you can confirm or change the column assignments. Auto-detected fields: email, first_name, last_name. Any additional columns become custom fields.

Duplicate handling: if a contact's email already exists in your account, the import updates their fields rather than creating a duplicate. Existing subscription status (subscribed / unsubscribed) is preserved unless you explicitly choose to overwrite it.

Custom fields

Custom fields let you store any data alongside a contact — plan tier, company name, signup date, product category — and use it for personalisation in campaigns or filtering in segments.

Field types

Type	Example values	Use case
Text	`pro`, `Acme Corp`	Plan tier, company name, tags
Number	`42`, `1250`	Order count, revenue, score
Date	`2026-01-15`	Signup date, trial expiry, last purchase
Boolean	`true` / `false`	Has completed onboarding, paying customer

Using fields in campaigns

Reference any field in your email subject or body with double curly braces:

Subject: {{first_name}}, your {{plan}} plan summary is ready

Hi {{first_name}},

Your account at {{company}} has been active since {{subscribed_at}}.

Fallback values: use the pipe syntax to provide a fallback if the field is empty: {{first_name | there}} renders as "there" if first_name is blank.

Dynamic segments

Segments are filtered views of your contacts list. They are dynamic — membership is recalculated at send time, so a segment always reflects your current data.

Creating a segment

Go to Contacts → Segments → New segment
Add one or more filter conditions
Choose AND (contact must match all conditions) or OR (contact must match any condition)
Name the segment and save

Available filter conditions

Field	Operators
Email	contains, does not contain, ends with
First / last name	is, is not, contains
Any custom text field	is, is not, contains, is empty, is not empty
Any custom number field	equals, greater than, less than, between
Any custom date field	before, after, between, in the last N days
Subscription status	subscribed, unsubscribed
Date added	before, after, in the last N days

Suppression list

The suppression list contains email addresses that will never receive campaigns — hard bounces, spam complaints, and manual unsubscribes. SES Mailbox maintains this automatically but you can also manage it manually.

How suppressions are added automatically

Hard bounce: added immediately when AWS SES reports a permanent delivery failure
Spam complaint: added immediately when a recipient clicks the spam button (via ISP feedback loops)
Unsubscribe: added when a recipient clicks the one-click unsubscribe link in any campaign

Importing suppressions from another ESP

If you are migrating from Mailchimp, Klaviyo, or another platform, import your historical unsubscribes and bounces before importing your active contacts:

Export unsubscribes and bounces from your previous ESP
In SES Mailbox: Contacts → Suppression → Import CSV
Upload the file — only the email column is required
Select reason: Unsubscribed or Bounced

Import suppressions first. If you import active contacts before suppressions, those contacts may receive a campaign before the suppression list is loaded. Always do suppressions first.

Manually suppressing an address

Go to Contacts → Suppression → Add address and enter the email address. Choose the reason (Unsubscribed, Bounced, or Other). The address is immediately excluded from all future sends.

Removing from the suppression list

If a contact asks to be re-subscribed (e.g. they unsubscribed by mistake), find them in Contacts → Suppression, select them, and click Remove from suppression. They will be eligible to receive campaigns again. Keep a record of explicit re-subscribe consent for GDPR compliance.

Exporting contacts

Go to Contacts → Export CSV. You can export all contacts, a specific segment, or just your suppression list. Exports are available on both Free and Pro plans. Large exports (100k+ contacts) are emailed to you as a download link within a few minutes.