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.
Upload a CSV or TXT file to import multiple subscribers at once.
File Requirements:
- Required fields:
email*,name*(asterisk indicates required) - Custom fields: Any additional fields you've created for your subscribers
- Format: Comma-separated values, one subscriber per row
Template Examples:
Basic Template
email*,name*,custom_field1,custom_field2
[email protected]*,John Doe*,Value1,Value2
[email protected]*,Jane Smith*,Value3,Value4
Advanced Template
email*,firstname*,lastname*,custom_field1,custom_field2
[email protected]*,John*,Doe*,Value1,Value2
[email protected]*,Jane*,Smith*,Value3,Value4
Required columns are marked with asterisks (*). The system automatically recognizes and combines name-related columns (name, firstname, lastname) into a single full name field.
Import Options:
- Add to groups: Select existing groups to add imported subscribers to
- Send verification email: Send confirmation emails to new subscribers
We automatically clean duplicate email addresses and filter out invalid emails. Duplicate handling is automatic - existing subscribers are updated rather than duplicated. Make sure your data includes proper permission for emailing these subscribers.
When verification emails are sent, subscribers remain in "NEW" status and won't receive any newsletter emails until they click the verification link in their email.
Add individual subscribers directly through the interface.
Required Information:
- Email address: Valid email format required
- Name: Subscriber's full name
Optional Fields:
- Custom fields: Any additional data fields you've configured
- Group membership: Add the subscriber to one or multiple groups
- Verification email: Send a confirmation email immediately
Process:
- Fill in email and name (required)
- Add any custom field data
- Select groups to add the subscriber to
- Choose whether to send verification email
- Click "Add subscriber"
Import subscribers programmatically using the bulk-upsert API endpoint.
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()
email
string required
The subscriber's email address. Must be a valid email format. This is the only required field for each contact.
name
string
The subscriber's full name. Optional - if not provided, will use the email username portion.
verification_id
string
ID of a verification email variant. When provided, sends a verification email and sets the contact state to "NEW". Optional - if omitted, contact is marked as verified automatically.
state
string
Contact status. Valid values: "VERIFIED", "UNVERIFIED", "REMOVED". Can only set to "VERIFIED" if contact is currently "REMOVED". Optional - defaults based on verification settings.
fields
object
Custom field data as key-value pairs. Values are merged with existing fields (not replaced). Field types are automatically converted (dates, numbers). Optional.
group_add
string[]
Array of group IDs to add the contact to. Groups must exist and belong to your organization. Optional.
group_remove
string[]
Array of group IDs to remove the contact from. Groups must exist and belong to your organization. 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 from your verification email variants (if sending verification emails)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, subscribers are set to verified status automatically - With
verification_id, contacts remain in "NEW" state until verification email is clicked - State changes are restricted based on current contact status
- Values from the
fieldsobject that are not included in the API call will not be updated/inserted - Group IDs must belong to your organization or the operation will fail
Exporting Subscribers
Download your subscriber data as a CSV file for external use or backup.
Export Options
Export All
Location: Top-right "Export all" button
Scope: Downloads all subscribers in your organization
Use case: Complete subscriber backup or migration
Export Filtered
Location: Top-right "Export filtered" button (only with filters applied)
Scope: All subscribers matching current filters
Use case: Export subscribers from specific segments or groups
Export Selected
Location: Group actions menu → "Export CSV"
Scope: Only selected subscribers from current view
Use case: Export filtered or manually selected subscribers
Export Behavior
Column Selection:
- Only visible columns are included in the export
- Use the column visibility controls to show/hide fields before exporting
- Basic fields (Email, Name, Added At, State) are visible by default
- 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
Before exporting, adjust your column visibility settings to include only the data fields you need in your CSV file.
Export Process
Choose Export Method
- Click "Export all" for complete subscriber list
- Or apply filters, select subscribers, then use "Export CSV" from group actions
Configure Columns
Use column visibility controls to show/hide fields in the export
Confirm Export
Review the confirmation dialog for large exports
Download File
CSV file downloads automatically to your default download folder :::
Large exports (10,000+ subscribers) may take several minutes to process. You'll receive a notification when the export begins.
Bulk Operations and Export
When using group actions for export:
- Select All: Exports all subscribers in current filtered view
- Individual Selection: Exports only checked subscribers (up to 10,000)
- Filtered Results: Applies current query builder filters to the export
The export respects all active filters, segments, and group restrictions. Only subscribers visible in your current view will be included in the CSV.