Import / Export
Learn how to bulk import subscribers from files or API, and export your subscriber data for external use.
Importing Subscribers
Add subscribers to your newsletter in bulk using CSV files, individual entries, or through the API. On the Subscribers page, click Add subscribers and choose Import from a file (CSV/TXT), Add one subscriber or Add through the API. The Add subscribers page that opens asks "How do you want to add subscribers?" with three cards — Import a file, Add one subscriber and Use the API — and you can switch between them there.
Upload a CSV or TXT file to import multiple subscribers at once. The page walks you through five numbered steps: Upload your file, Check the columns, Add to groups (optional), Did these people agree to get your emails? and Review and import.
File Requirements:
- Email column (required): a column whose header contains the word "email", for example
emailorE-mail address. Without one the page shows No email column found and the import can't start - Name columns (optional): any column whose header contains "name" — first and last names are joined into one full name
- Custom fields: a column whose header is exactly the Merge tag of a custom field you've created. Any other column is skipped and shown as Not imported
- Format: Comma-separated values, one subscriber per row, column names in the first row without extra spaces. Drop the file on the box that says Drop your CSV or TXT file here, or click it to choose one
Template Examples:
email*,name*,custom_field1,custom_field2
[email protected]*,John Doe*,Value1,Value2
[email protected]*,Jane Smith*,Value3,Value4
email*,firstname*,lastname*,custom_field1,custom_field2
[email protected]*,John*,Doe*,Value1,Value2
[email protected]*,Jane*,Smith*,Value3,Value4
The examples mark the main columns with asterisks (*); only the email column is required. The system automatically recognizes and combines name-related columns (name, firstname, lastname) into a single full name field.
Upload your file: Download template gives you a ready-made file with the email and name columns plus the merge tag of each of your custom fields, and See example files shows the two examples above.
Check the columns: once a file is chosen, a table lists every column in it with two sample values and what it will be imported as — Email, Name, one of your custom fields, or Not imported — and sums up how many columns will be imported. If a column you want is skipped, rename its header to a field's merge tag, or create the field first (Open Fields takes you to the Fields view).
Import Options:
- Add to groups (optional): Select existing groups; everyone in the file joins them
- Did these people agree to get your emails?: Choose Yes, they signed up to add them straight away, with no confirmation email, or Ask them to confirm first to send a confirmation email so they join only once they click the link in it. With the second choice you also pick the Confirmation email to send; Edit confirmation emails opens your list of confirmation emails
Review and import: a summary shows the File, Rows found, Columns, Groups and Confirmation email. Click Import subscribers (with the number of rows in brackets) to start. When it finishes you see how many subscribers were imported, how many duplicates were left out, and a List cleaned message if addresses were skipped.
no-reply@, postmaster@, or abuse@). Duplicates are skipped — the existing subscriber is left unchanged. You get a List cleaned summary with a per-reason breakdown, for example "Skipped 42 addresses that can't be delivered to: 30 invalid, 5 disposable, 7 system/no-reply." The same gate runs on the bulk-upsert API, which returns the skipped counts in its response.Add individual subscribers directly through the interface.
Required Information:
- Email: Valid email format required
- Name: Subscriber's full name
Optional Fields:
- Custom fields: Any additional data fields you've configured, behind Show custom fields (Hide custom fields puts them away again)
- Add to a group: Add the subscriber to one or more groups
- Did these people agree to get your emails?: Yes, they signed up adds the subscriber straight away; Ask them to confirm first sends a confirmation email, which you pick under Confirmation email to send
Process:
- Fill in email and name (required)
- Click Show custom fields (it appears once you have created custom fields) and add any custom field data
- Select groups under Add to a group
- Choose whether to ask the subscriber to confirm first
- Click Add subscriber :::
Import subscribers programmatically using the bulk-upsert API endpoint. The Use the API card shows an example call and notes, plus two pickers, Check verification email variant IDs and Check group IDs, that show the ID to put in the call for each of your confirmation emails and groups.
Endpoint: POST https://yaplet.com/api/newsletter/contacts/bulk-upsert
const response = await fetch("https://yaplet.com/api/newsletter/contacts/bulk-upsert", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Y-API-Key": "your_api_key_here",
},
body: JSON.stringify({
contacts: [
{
email: "[email protected]",
name: "John Doe",
verification_id: "verification_variant_id",
state: "VERIFIED",
fields: {
custom_field_1: "value_1",
custom_field_2: "value_2",
},
group_add: ["group_id_1", "group_id_2"],
group_remove: ["group_id_3"],
},
],
}),
});
const result = await response.json();
curl -X POST "https://yaplet.com/api/newsletter/contacts/bulk-upsert" \
-H "Content-Type: application/json" \
-H "Y-API-Key: your_api_key_here" \
-d '{
"contacts": [
{
"email": "[email protected]",
"name": "John Doe",
"verification_id": "verification_variant_id",
"state": "VERIFIED",
"fields": {
"custom_field_1": "value_1",
"custom_field_2": "value_2"
},
"group_add": ["group_id_1", "group_id_2"],
"group_remove": ["group_id_3"]
}
]
}'
<?php
$url = "https://yaplet.com/api/newsletter/contacts/bulk-upsert";
$apiKey = "your_api_key_here";
$data = [
"contacts" => [
[
"email" => "[email protected]",
"name" => "John Doe",
"verification_id" => "verification_variant_id",
"state" => "VERIFIED",
"fields" => [
"custom_field_1" => "value_1",
"custom_field_2" => "value_2"
],
"group_add" => ["group_id_1", "group_id_2"],
"group_remove" => ["group_id_3"]
]
]
];
$options = [
"http" => [
"header" => "Content-Type: application/json\r\nY-API-Key: $apiKey",
"method" => "POST",
"content" => json_encode($data)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
import requests
import json
url = "https://yaplet.com/api/newsletter/contacts/bulk-upsert"
api_key = "your_api_key_here"
payload = {
"contacts": [
{
"email": "[email protected]",
"name": "John Doe",
"verification_id": "verification_variant_id",
"state": "VERIFIED",
"fields": {
"custom_field_1": "value_1",
"custom_field_2": "value_2"
},
"group_add": ["group_id_1", "group_id_2"],
"group_remove": ["group_id_3"]
}
]
}
headers = {
"Content-Type": "application/json",
"Y-API-Key": api_key
}
response = requests.post(url, json=payload, headers=headers)
result = response.json()
verification_id). Contacts that bounced or complained keep their state — their other fields still update. An unsubscribed contact can't be brought back with state, only by the person confirming a new confirmation email (see verification_id). Optional - defaults based on verification settings.null or "" to clear it; any other value that isn't a number is skipped, and the subscriber keeps their current value. Optional.Code Example Explanation:
- URL:
https://yaplet.com/api/newsletter/contacts/bulk-upsert- The full API endpoint URL - Headers:
Content-Type: application/json- Required for JSON payloadY-API-Key: your_api_key_here- Replace with your actual API key from the dashboard
- Request Body: Contains a
contactsarray with subscriber objects - Replace placeholders:
your_api_key_here→ Your actual API key[email protected]→ The subscriber's emailverification_variant_id→ ID of one of your confirmation emails (if asking new subscribers to confirm)group_id_1,group_id_2→ Actual group IDs from your organizationcustom_field_1,custom_field_2→ Your custom field tag namesvalue_1,value_2→ The actual values for custom fields
API Notes:
- Only the
emailfield is required for each contact, everything else is optional - Without
verification_id, new subscribers are set to verified status automatically — an unsubscribed contact sent again without one stays unsubscribed - With
verification_id, new and removed contacts start in "NEW" state and move to "UNVERIFIED" once the confirmation email is sent, staying there until it is clicked - A contact that unsubscribed, bounced or complained is never switched back to subscribed or verified by the API — not even if you deleted it and send it again
- The response lists the contacts with the state each one actually has after the call, so you can see which ones kept their state
- Values from the
fieldsobject that are not included in the API call will not be updated/inserted - Group IDs that don't belong to your organization are ignored — the contact is still saved, it just isn't added to or removed from that group
Exporting Subscribers
Download your subscriber data as a CSV file for external use or backup.
Export Options
Export All
Location: Top-right Export menu → Export all subscribers
Scope: Downloads all subscribers in your organization, whatever filter is on
Use case: Complete subscriber backup or migration
Export Filtered
Location: Top-right Export menu → Export filtered subscribers (only shown while a filter, segment or group is applied)
Scope: All subscribers matching current filters
Use case: Export subscribers from specific segments or groups
Export Selected
Location: Actions menu → Export CSV
Scope: Only selected subscribers from current view
Use case: Export filtered or manually selected subscribers
Export Behavior
Visible columns:
- Only visible columns are included in the export
- Use the Columns menu above the table to show/hide fields before exporting
- Basic fields (Email, Name, Added At, State) and Engagement are visible by default
- Engagement and the activity columns (Email provider, Last active, Last opened, Last clicked, Clicks, Emails received, Last emailed) can be included as export columns — the activity columns stay hidden until you switch them on in Columns. They're export-only, so they can't be used as import columns. A score or count of zero exports as
0, not an empty cell - Custom fields are hidden by default unless enabled
File Format:
- Format: Comma-separated values (.csv)
- Encoding: UTF-8
- Headers: Column names in first row
- Data: One subscriber per row
Export Process
Choose Export Method
- Click Export → Export all subscribers for the complete subscriber list
- Or apply filters and choose Export → Export filtered subscribers
- Or select subscribers, then use Actions → Export CSV
Configure Columns
Use the Columns menu to show/hide fields in the export
Confirm Export
Confirm the dialog that asks "Are you sure you want to export these subscribers?" — it reminds you that the file contains the currently visible columns
Download File
CSV file downloads automatically to your default download folder :::
Bulk Operations and Export
When using Actions → Export CSV:
- Select all: Exports all subscribers in current filtered view
- Ticked subscribers: Exports only checked subscribers (up to 10,000)
- Filtered Results: Export filtered subscribers applies the current Filter conditions to the export