Contacts are the foundation of your email marketing efforts in Notifuse. They represent your subscribers, customers, and prospects, complete with detailed profiles, custom fields, and engagement history.
Contacts in Notifuse are comprehensive customer profiles that store subscriber information, preferences, and engagement data. They support flexible data storage through predefined fields and can be associated with multiple mailing lists.
The email address is the unique identifier of a contact: it is the primary key in the database, and every upsert operation (contacts.upsert, contacts.import, and the contact embedded in transactional.send) matches contacts by email address only:
New emails: Automatically creates a new contact
Existing emails: Updates the existing contact with provided fields
Null values: Setting any field to null removes that value from the contact
external_id is an optional reference to the contact in your own system (for example, your application’s user ID). It is stored, searchable, and returned by the API, but it is not a unique key:
It is never used to match contacts during upserts.
Notifuse does not prevent several contacts from sharing the same external_id.
If several contacts share the same external_id, contacts.getByExternalID returns only one of them (which one is not defined).
Because the email address is the contact’s identity, upserting the same external_id with a new email address creates a second contact — it does not update the email of the existing one. When a user changes their email address in your system:
Fetch the old contact with contacts.getByEmail to retrieve its profile and its list subscriptions with their statuses.
Upsert a contact with the new email address, sending the full profile (upserts merge fields, so include every field you want to keep, such as external_id, names, and custom fields).
Re-create the list subscriptions on the new contact with lists.subscribe.
Delete the contact with the old email address using contacts.delete.
Preserve opt-out statuses when re-creating subscriptions. If the old contact had unsubscribed,
bounced, or complained on a list, do not re-subscribe the new email address to that list:
the new contact starts with a clean slate, and blindly re-subscribing silently resets an
opt-out — a consent violation (GDPR / CAN-SPAM) that can hurt your sender reputation.
Also keep in mind:
Message history and segment memberships are keyed to the email address. They stay attached to the old email address and are not transferred to the new contact.
Active automations: deleting the old contact drops it from any automation it is currently progressing through; the new contact does not resume its position.
Notifuse includes a powerful real-time contact segmentation engine that allows you to create dynamic audience segments based on contact properties and engagement behavior. Segments automatically update as contact data changes, ensuring your targeting remains accurate and current.
The segmentation engine leverages contact timeline data introduced in version 7.0, which tracks all contact interactions including messages, webhook events, and profile mutations. Activity events include granular kind field types (e.g., email.opened, email.clicked, web.pageview) enabling precise behavioral targeting. All timestamps are stored in UTC timezone and can be evaluated in user-specified timezones for date-based conditions.
Segments have their own Segments permission: read lists segments and opens one, write creates, edits, deletes and rebuilds them, and runs, resets or deletes their background build tasks.Previewing a segment while you build it, and listing the contacts a segment currently matches, additionally require the Contacts read permission — both answer questions about your contacts rather than about the segment definition. A member holding Segments read alone can work with segment definitions, but not see who is in them.Preview accepts any definition sent to it, not just a saved segment. Someone holding Segments read together with Contacts read can therefore ask counting questions about any contact attribute, list membership, custom event or timeline entry, one count at a time.
Notifuse provides a powerful CSV import feature that streamlines the process of adding multiple contacts to your workspace. The import system is designed to be intuitive and robust, handling large datasets efficiently.
The CSV importer automatically detects and suggests field mappings based on your CSV column headers. Common column names like “email”, “first_name”, “last_name”, and “phone” are automatically matched to their corresponding contact fields. For custom or non-standard column names, you can manually map each CSV column to the appropriate contact field through an intuitive interface.
During the import process, you can select one or multiple mailing lists to add your contacts to. This allows you to immediately segment your imported contacts and ensures they’re properly organized within your workspace. All imported contacts will be automatically subscribed to the selected lists upon successful import.
The import process includes automatic progress saving, which means if your import is interrupted due to network issues or browser closure, you can resume from where you left off. This is particularly valuable when importing large CSV files with thousands of contacts, ensuring no data is lost during the process.
Importing needs the Contacts write permission. Selecting one or more mailing lists during the import needs Lists write as well.Bear in mind what an import does: every field a row carries overwrites the stored value on the matching contact. A single import can rewrite your whole contact database, so treat Contacts write as that level of access rather than as “can add contacts”.
Read covers contact records and their full profiles, the contact timeline, and the custom events recorded against contacts. It is also required — alongside the matching Lists or Segments grant — to enumerate the addresses inside a list or a segment, and to set cc or bcc on a transactional send.
Write covers creating and updating contacts, deleting them, bulk-overwriting them through a CSV or API import, and recording custom events. Changing a contact’s subscription status on a list needs Lists write as well.
Write is not “can add contacts”: it deletes permanently, and it overwrites in bulk.Three grants reach contact data without Contacts write, which is worth knowing before you hand any of them out:
Lists write on its own creates or overwrites a complete contact record. Subscribing an address through /api/lists.subscribe writes every field the request carries, and can subscribe someone to a list that is not public.
Automations write sends the complete contact record to any URL a webhook node names, and nothing checks permissions while an automation runs.
Transactional write creates the recipient contact as part of sending. Without Contacts write, only the email address is stored and an existing contact is never modified — see Transactional API.
