Contacts

Manage your subscriber lists, organize contacts into groups, handle imports and exports, and maintain clean subscription data.

Overview

Contacts are the foundation of your email marketing. GoodPostal stores contacts per workspace with full tenant isolation; your data is always separate from other accounts. Each contact has an email address and first name, optional last name, phone, and address details, and can belong to multiple groups.

Adding Contacts

Manual Entry

Navigate to Contacts and click Add Contact. Email address and first name are required; last name, phone, and the address fields are optional. After saving, add the contact to groups from the contacts list using Add to Group.

CSV Import

For bulk imports, use the CSV import feature. Your CSV file should include headers matching the expected fields.

email,first_name,last_name,phone,city,state,zip_code,country
jane@example.com,Jane,Doe,555-0101,Austin,TX,78701,US
john@example.com,John,Smith,,Denver,CO,80202,US
alex@example.com,Alex,Johnson,,,,,

1. 1

   Prepare your CSV file

   Your file needs an "email" column. Everything else is optional: first_name, last_name, phone, address_line_1, address_line_2, city, state, zip_code, and country. Header names must match those exactly, though capitalization does not matter, and the file must be UTF-8 encoded.
2. 2

   Upload the file

   Click "Import Contacts" and select your CSV file. There is no column-mapping step, so a column whose header does not match one of the names above is ignored. Use the "Download CSV template" link in the import dialog if you want a correctly formatted starting point.
3. 3

   Watch it run

   The import starts as soon as the upload finishes and runs in the background. GoodPostal shows a live progress bar plus a summary of how many rows are new, duplicate, or in error.

Migrating from Mailchimp or another platform

Drop all of your old platform's export files into the import dialog at once, exactly as they were downloaded, and with no header editing. Mailchimp column names like Email Address are recognized automatically, the combined Address column is split into its parts, and files named subscribed_…, unsubscribed_…, or cleaned_… preselect the right handling for each file. You can change any file's handling before importing with its Import as choice: Subscribed (the default), Unsubscribed, or Bounced.

Rows imported as Unsubscribed or Bounced are added to your list but recorded as permanent opt-outs: they are never emailed, and if a later import or sync includes the same address again, it stays opted out. Files can be uploaded in any order.

Contact Groups

Groups let you organize contacts into segments for targeted campaigns. A contact can belong to multiple groups simultaneously.

• Create a group - Open Contacts and click the add-group icon at the top of the Groups sidebar, or choose "Create New Group" from the Add to Group menu. Give it a name and optional description.
• Add contacts to groups - Select contacts from the list and use the "Add to Group" action.
• Remove from groups - First select the group in the Groups sidebar, then select the contacts and click "Remove from Group". The button appears only when exactly one group is selected, because it needs to know which group to remove them from.

Subscription Management

GoodPostal automatically handles unsubscribe requests. Every email sent includes an unsubscribe link. Clicking it opens a confirmation page, and the contact is unsubscribed as soon as they confirm. Mail clients that show their own built-in unsubscribe button take effect without that extra step.

You can also update a contact's subscription status yourself, using the "Subscribed to emails" switch in the Edit Contact dialog on the Contacts page, or the bulk unsubscribe action for several contacts at once. Contacts who have unsubscribed will not receive future campaigns unless they re-subscribe.

An opt-out belongs to the address, not to the contact record. It survives deleting the contact, emptying the trash, importing the address again, and renaming another contact onto it. Re-adding someone who opted out still creates the contact, but as unsubscribed, and your import summary tells you how many landed that way. AI assistants cannot re-subscribe them, and neither can the API endpoints that create or update a contact.

There are three ways back. The recipient confirms a new subscription through one of your forms; an administrator turns the "Subscribed to emails" switch back on for that one contact; or a system of your own sends the opt-in it just collected to the subscribe endpoint of the API, which accepts it only with a record of consent dated within the last 24 hours and after the opt-out. An address that hard bounced is never re-subscribed by the API at all.

Custom Fields

Custom fields are extra pieces of information attached to a contact beyond the standard name, email, and address, such as a donor tier, a sponsor count, or an ID from another system. They arrive through the REST API or a connected system rather than manual entry or CSV import, and they show up as a read-only list in a contact's Edit dialog once present.

Create your custom fields under Settings > Custom Fields to give each key a friendly name and a type, so your team sees "Sponsor count" instead of sponsor_count and a yes or no field reads as Yes or No. Defining is optional and it never changes what your system may send: a key that arrives without a definition is still stored, still shown, and still filterable.

To filter contacts by a custom field, click Custom field in the Contacts filter bar, choose a field and a comparison, and enter a value if the comparison needs one. The comparisons on offer follow the field's type, so a yes or no field gives you a Yes or No picker and a date field gives you a date picker. The button appears once you have defined a field or at least one contact has one. Combine it with the other filters to narrow the list, then use Add to Group to build a group from the filtered result, export it, or leave it applied while you browse.

Custom fields also work in your emails. Write {{ sponsor_count }} in a subject line or in your content and each contact sees their own value, with a fallback for anyone who has none. Fallbacks, date and currency formats, and if/else blocks are covered in the merge tags section of the campaigns guide.

Exporting Contacts

Export your contacts as a CSV file from the Contacts page. Use the filter and group options to export specific segments. The export includes email, name, subscription status, and group memberships.

Custom fields are not in the file by default. Choose Select columns in the export dialog and tick the ones you want under Custom fields. If you are already filtering by a custom field, those fields are ticked for you.

Contact Limits

GoodPostal has no per-contact pricing. Ever. Sends are metered at $0.05 per 1,000, billed from your first email (no included allowance). Store as many contacts as you like; your bill only moves when you send. You also pay your email sending service separately for the actual emails you send.

Contacts are unlimited on the paid plan. The 14-day trial holds up to 10,000 contacts, and subscribing lifts the cap.