Subscribers API
Manage your email subscribers, add tags, and segment your audience.
Overview
Subscribers are the core of your email list. Each subscriber has an email address, optional profile information, and tags for segmentation.
Add Subscribers
Add new contacts via API with automatic deduplication.
Tag & Segment
Organize subscribers with tags for targeted campaigns.
Query & Filter
Retrieve subscribers with pagination and filtering.
Endpoints
/api/v1/subscribersCreate Subscriber
Add or update a subscriber. Uses upsert logic—if the email already exists, the subscriber record is updated.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Required | Subscriber email address | |
| first_name | string | Optional | First name for personalization |
| last_name | string | Optional | Last name for personalization |
| tags | string[] | Optional | Tags for segmentation |
| domain_id | uuid | Optional | Associate with a verified domain |
| external_id | string | Optional | Your system's ID for correlation (e.g., "customer_123") |
| metadata | object | Optional | Custom key-value data (merged into attributes) |
Example Request
curl -X POST https://sendmailos.com/api/v1/subscribers \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"tags": ["newsletter", "premium"],
"external_id": "customer_123",
"metadata": {"plan": "pro", "source": "website"}
}'Response (201 Created)
{
"success": true,
"subscriber": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "[email protected]",
"status": "subscribed",
"source": "api",
"external_id": "customer_123",
"attributes": {
"tags": ["newsletter", "premium"],
"plan": "pro",
"source": "website"
},
"created_at": "2024-01-15T10:30:00Z"
}
}/api/v1/subscribersList Subscribers
Retrieve all subscribers with pagination support.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | number | 20 | Results per page (max 100) |
| offset | number | 0 | Number of records to skip |
Example Request
curl -X GET "https://sendmailos.com/api/v1/subscribers?limit=50&offset=0" \
-H "Authorization: Bearer sk_live_..."Response
{
"success": true,
"subscribers": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"status": "subscribed",
"tags": ["newsletter", "premium"],
"source": "api",
"created_at": "2024-01-15T10:30:00Z",
"primary_domain": {
"id": "...",
"domain_name": "yourcompany.com"
}
}
],
"total": 1234,
"limit": 50,
"offset": 0
}Subscriber Status
Subscribers can have one of the following statuses:
| Status | Description |
|---|---|
subscribed | Active subscriber, receives all emails |
unsubscribed | Opted out of marketing emails |
bounced | Email address hard bounced, no emails sent |
complained | Marked email as spam, automatically suppressed |
Using Tags
Tags help you segment your audience for targeted campaigns.
Tag naming conventions
Use lowercase, hyphenated tags like early-adopter, premium-user, or webinar-2024 for consistency.
// Send campaign to subscribers with specific tags
POST /api/v1/campaigns/send
{
"subject": "Exclusive Premium Offer",
"tags": ["premium", "active"], // Only premium AND active subscribers
"html": "..."
}