Importing a list
Upload a file or sync from WinRed or Anedot. A list has one of four sources:
A list is
processing while the import runs and ready when it is done. You
cannot send to a list that is not ready; the API returns
409 EMAIL_LIST_NOT_READY.
Where the uploader lives
Every file you upload goes through one page: Assets > File Uploads. Choose who owns the upload under Upload to, then drop the file. A CSV or TXT file becomes a list; there is no upload type to pick. On the setup card, choose Audience under What is this?, then choose the email column (pre-filled from the file) and, if the file also has phone numbers, the phone column. The file you upload is the list, named after the file unless you rename it, so there is no list to create first. Every other column is matched for you: the standard fields a header names, and every other column as a merge field named from its header. Skip a column you do not want or rename a merge field. The emails belong to the whole organization the list is uploaded to. The card shows one checkbox, This list was purchased or rented, which is unchecked by default. Check it for a purchased or rented list; it is then sent more gradually. One list holds phone numbers and emails. A file with both columns becomes one list with both, and every list is on one page, Assets > Lists. A list card shows its phone numbers and, when it has emails, an Emails section with the total, sendable, unsubscribed, and bounced counts and the quality grade; the list’s page shows both. Deleting a list removes its phone numbers and its emails. Two lists can share a name. A campaign combines lists by attaching several of them, exactly as a texting project attaches lists, so there is no reason to import two files into one list. The old Email > Lists links still work and open the same list on Assets > Lists, so existing bookmarks are fine.Importing over the API
POST /v1/contact-lists/import is the one list import, for phone numbers,
emails, or both. Give it an HTTPS URL to a CSV you host, a list_name, and the
column that holds the email address; it fetches, checks, and commits the file as
a new list.
tag_ids
and tag_names put those tags on every contact in the file (a name that does
not exist yet is created), and tags_column names a column whose cells hold
each row’s own tags, separated by commas, semicolons, or pipes.
400. A tags_column that would create more than 100 new tags fails the
import, so check that it names the right column. A failed import says why: read
import.error on GET /v1/contact-lists/{id} (and email.error for the email side).
It is { code, message }, with code TAG_COLUMN_TOO_MANY_TAGS for that case and
IMPORT_FAILED for any other failure, and message is safe to show to your user.
Both are null unless the import failed.
Add phone_column to bring in phone numbers in the same list. email_domain_id
scopes the emails to one sending domain; omitting it leaves the list available
to every campaign. acquired is optional and defaults to false; true declares a purchased or
rented list, which is sent more gradually.
consent is optional. It is allowed only for an audience import with an
email_column; sent with any other combination it returns 400. Omit it and no
consent record is stored. When you send it, source is one of donation_form,
petition, signup_form, event, purchased, rented, or other, and note
is optional text up to 1000 characters. Unknown keys inside consent or
merge_tags return 400; unknown top-level fields in the request body are
ignored.
Name the email column yourself: the API does not guess it. A column that is not
in the file returns 400 VALIDATION_ERROR with details.headers listing the
headers it read, so the retry can name the right one. Columns other than the
ones you chose become merge fields automatically. If you send merge_tags,
phone numbers map only the columns you name, while emails map the named columns
and every other column by its default name. Custom field names for emails must
start with a lowercase letter and use only lowercase letters, digits, and
underscores, at most 64 characters. Every refusal happens before anything is
stored.
The response is 202 with the list’s list_id and an email_import. The
import runs in the background; poll GET /v1/contact-lists/{list_id} until
email.status is ready or failed. The email object carries the counts and
removed_at_upload. When it is failed, email.error gives the reason.
POST /v1/email/lists/import was removed. To move a call over: send name as
list_name, the mapping entry whose value is email as email_column, and
the other mapping entries as merge_tags; email_domain_id and acquired carry
over unchanged, and consent is optional. See
Import List for every field.
What import removes and holds back
Every import, from the uploader or the API, applies the same checks:- Malformed addresses are rejected and reported. This includes Gmail
addresses Gmail could never have issued: a Gmail username is 6 to 30
letters, digits and dots, so
abc@gmail.comorjane_doe@gmail.comis removed as malformed. - Likely typos in the domain are skipped, not corrected. A row whose domain
is a known misspelling of a major mailbox provider, such as
gmial.com, is counted in the import summary as “Likely typo in the domain”. Fix the address in your file and import it again. - Role addresses such as
info@,admin@, andsales@are always removed. They reach a shared inbox rather than a person and complain at a far higher rate than personal addresses, so there is no option to keep them. - Disposable addresses from throwaway-mailbox services are removed. The list we check covers several thousand such domains.
- Yahoo-run mailboxes are removed from every list: Yahoo, AOL, AT&T, Verizon, Cox, Frontier and the other domains Yahoo hosts, detected by the domain’s mail servers so a provider that moves to Yahoo is covered. Recipients at those providers report political email as spam many times more often than anyone else, and one shared sending reputation carries every customer. The import summary counts them; the same rule applies to contacts added over the API and to donor-platform syncs. There is no option to keep them.
- High-complaint providers are removed too. When the mailboxes at one provider report our email as spam at an unusually high rate, we remove that provider’s addresses from every upload and never send to them. Today that is windstream.net. Existing lists were cleaned, sends already queued to those addresses are skipped, and the list’s “removed at upload” breakdown shows them. There is no option to keep them.
removed_at_upload.
- Addresses that cannot receive mail, such as a domain with no mail server, and addresses that already bounced or complained on this platform, are removed, as are duplicate rows in the same file.
- Addresses currently held by screening are imported but held back, and the
import summary reports them as
screened. See Address screening at send time.
Donor syncs and segments
Two of the four sources are worth calling out because they are not files: WinRed and Anedot syncs build an email list from your donor records automatically, so people who give keep arriving on the list without anyone exporting a CSV. Consent comes from the donation form itself, which is the cleanest provenance an email list can have. Create one from Assets > Lists > New Dynamic List; a feed is one list, holding its donors’ phone numbers and emails, and the list’s page shows the connection details and settings. The same picker offers Recent openers and Recent clickers: lists of everyone who opened or clicked a campaign in a window you choose, refreshed nightly. A refund can park a donor off the list, and a later gift brings them back; retention works the same way. These lists are managed through the connection rather than deleted, so the Delete action is not offered on them. Segments are lists built from contacts already in the platform, using rules rather than a file. Engagement rules are the useful ones: everyone who opened in the last 30 days, everyone who clicked a particular campaign, everyone who has not engaged in 90 days. Giving rules read your synced donations: total given, recurring, gave recently, number of gifts, any single gift above an amount, and the donation source (refcode, source code, UTM parameters, page name). Giving is counted net of refunds: a refunded or charged-back gift does not count toward a total or a gift count, and a gift that arrives through both a webhook and a scheduled report is counted once. A random split rule takes a stable slice of a list, so two segments with 0-50 and 50-100 never overlap; that is how you run two campaigns against halves of one list. Because a segment is defined by its rules, it reflects the current state of your contacts each time you use it rather than a snapshot from the day you built it, and it can refresh nightly. A segment’s rules can also tag the matching contacts instead of creating a list; see Tags.Consent attestation
Every list requires a consent attestation when you create it: a short statement of how the people on it agreed to hear from you, plus an optional note. This is not a checkbox to click past. It is the record you will want if a complaint is ever escalated, and the honest answer determines what happens next. A list from your own donate-page opt-in behaves differently from a list you bought.Acquired lists
If a list came from anywhere other than your own sign-up flow, set itsacquired field. Doing so is in your interest, not against it: an acquired list
that is not declared is far more likely to trip a deliverability breaker
mid-send and pause your campaign.
An acquired list is not blocked from sending. Declaring it has one consequence:
warm-up runs on half steps. The daily ceiling is halved at every stage of
the warm-up ramp, so a
list with less certain provenance reaches mailbox providers more slowly.
List quality score
When an import finishes, the list gets a quality grade: Good, Fair or Bad. It is built from what the import measured and from our own history with the addresses:
The grade is the worst of these. Lists synced from WinRed or Anedot get the
same checks; they have no upload step, so they are graded on their addresses and
history alone, and re-graded weekly as new donors sync in. Lists under 500 rows
are not graded, and segments are not scored, since each is built from graded
lists.
- Good: sends normally.
- Fair: sends at the slower pace used for acquired lists while the domain is warming up, and the campaign checklist shows a warning.
- Bad: sends at the slower pace used for acquired lists, with a warning on the campaign checklist. Nothing to approve.
Address screening at send time
There is no separate cleaning step and no charge for one. Every campaign email is screened as it is sent, using the strictest setting of the mail provider’s automatic validation. An address it rates as likely undeliverable is not sent to. What happens to a screened address:- The message is recorded with status
suppressedand reasonauto_validation. - It is not counted as a bounce, so it does not count toward your bounce
rate or the deliverability breakers,
and it does not fire the
email.bouncedwebhook. - The address is held out of all sends on the platform for 90 days, for every organization. After 90 days it is checked again on its next send.
- The campaign report shows the total as Screened as invalid.
- You are billed the normal per-recipient email rate for it, the same as a bounce, because the message was handed to the mail provider.
Downloading a list
Download on the list page saves the file straight away, the same as a texting contact list. Every list offers two files, and an uploaded list a third:- Current list: the columns you imported, named as you mapped them and in
the order they arrived, followed by
email,status, andstatus_reason, showing each contact as it stands now. A contact the platform will no longer mail, for example an address mailbox providers reported as not existing, readssuppressedwith the reason. - Unmailed addresses: the sendable contacts this platform has never delivered to, in the same columns. This is the file to run through an address verification service when a campaign pauses on its unproven tail; upload the result as a new list and edit the campaign’s list.
- Original upload: the file exactly as you uploaded it.
Contact statuses
Only
subscribed contacts are mailed. The rest are excluded automatically, and
none of them can be restored by re-importing the same file.
Removing contacts
Removing an address unsubscribes it rather than deleting the row, because the row carries the bounce and complaint history that keeps it unmailed after your next import. To erase an address entirely, use forget this address.Unsubscribes, bounces, and the sunset policy
Unsubscribes, bounces, complaints, and the 90-day hold and 180-day sunset all work the same way regardless of which list an address is on, so they have their own page: Bounces, complaints, and unsubscribes. The short version: an address that bounces permanently or complains is never mailed again, automatically, unsubscribes are honored immediately, and contacts who have not engaged in 90 days stop being mailed before they can damage your reputation. Opening or clicking one of your emails counts as engagement and starts that clock over.Adding emails over the API
Over the API, emails reach a list the same way phone numbers do: import a CSV withPOST /v1/contact-lists/import, naming its email column as email_column (and its
phone column as phone_column when the file has both). The import creates the list;
there is no separate endpoint to create an empty list or to add or page through
addresses one call at a time. Poll GET /v1/contact-lists/{id} until email.status is
ready or failed; the email object carries the list’s counts and quality grade.
Unsubscribes, bounces, and complaints are on GET /v1/email/suppressions.
The /v1/email/lists endpoints were removed. A list is one
list for both channels, so every list endpoint is under /v1/contact-lists, and
list ids did not change:
