Bring your contacts in without losing consent

What an import actually writes

This article is part of the Mailprompt help centre. It explains the shape of a contact record, the two supported import paths and the checks that run after a write.

A contact is stored as a profile. The email address is the identity. Around it sit the name, the consent status, the consent source, the consent timestamp, list memberships, tags, custom properties and the event history. The import writes the profile and, optionally, adds it to a list.

The consent fields are the part that matters for compliance. A status of subscribed without a timestamp is refused, because the product cannot show when the permission was given. A status of never_subscribed is the safe default when a file does not include consent information. Pending means double opt-in was started but not confirmed, and marketing email is blocked until it is.

Through the assistant

The assistant can import a batch of up to five thousand contacts. Paste the rows or describe the file, including the column names and what each column means. Tell it which column holds the consent status and which holds the date, and say what to do with rows that have neither.

The assistant normalises email addresses, drops duplicates inside the batch, and reports how many rows were valid and how many were skipped. It does not invent consent. If a row says subscribed but has no date, the row is reported rather than silently downgraded.

Above one thousand contacts the assistant returns a snapshot and a count instead of writing. An owner or admin approves that snapshot, and the import continues with the approval id. The same rule applies whether the import comes from the chat, an MCP client or a script.

Through the API

The public API accepts list members through the lists endpoints. Create a list first, then add members in batches. The API uses API keys with the lists:write and profiles:write scopes, rejects a key passed in the query string, and applies the same consent rules as the assistant.

The API is the right route for a repeatable migration. Read the source export in your own script, map the columns to the documented fields, and post batches with an idempotency key so a retry does not duplicate a write. Keep the source row id in a property so a later reconciliation can find the contact again.

The API keys guide covers key creation, scopes and test mode. Test mode accepts a key that starts with mp_test_ and returns synthetic responses without storing anything, which is a safe way to check a mapping before the real run.

Consent, suppression and the order of checks

An import can add a subscribed contact, but it cannot override a suppression. After the write, the suppression list is applied. An address that hard-bounced, complained or was manually blocked stays blocked, whatever the file says. The profile may exist and belong to a list; it will not receive marketing email.

An unsubscribe works the same way. If a contact unsubscribed from an earlier send and appears in a new export as subscribed, the unsubscribe is kept. This is deliberate: a fresh file is not fresh consent.

After the import

Check three numbers before sending: how many rows were written, how many were skipped and why, and how many are suppressed. A large skip count usually means a column was misread or a date format did not parse. Fix the mapping and import again; profiles update in place rather than duplicating.

Build a segment from the new list and preview the count against the audience you expect. A list with more contacts than the source file suggests usually means the list already contained members from an earlier import. A list with fewer usually means duplicates or invalid addresses were removed.

Send a small, relevant campaign first. A large list that has not received mail in a long time will produce complaints if the first send is a broad promotion. The unsubscribes and compliance guide covers re-permissioning and list hygiene in more detail.

What is not built yet

There is no file-upload screen in the app and no one-click Klaviyo or Mailchimp importer. Plans for either would be a promise this page cannot keep. The assistant and the API are the supported paths today, and both are real, tested routes rather than a placeholder.

If a migration needs fields that the import does not accept, keep them as custom properties on the profile. A property is stored with the profile and can be used in a segment condition, so a source id or an original signup date does not have to be thrown away.