Send an Email
POST/v1/emails
Send an email to one or more recipients. Returns the email ID for tracking.
Request Body
to
string | string[]
required
Recipient email address(es)
HTML content of the email
Template ID (instead of html/text)
Variables for template rendering
ISO 8601 datetime for scheduled sending
Custom email headers (e.g., X-Custom-Header)
File attachments. Each object requires filename (string), content (base64-encoded string), and optionally content_type (MIME type string, defaults to application/octet-stream).
Custom tags for analytics. Array of objects with name and value string properties.[{ "name": "campaign", "value": "welcome" }]
Control open and click tracking per email. Properties: open (boolean, default true), click (boolean, default true).{ "open": true, "click": true }
Email priority level. One of high, normal (default), or low.
Basic Example
curl -X POST https://api.unosend.co/emails \
-H "Authorization: Bearer un_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "John Doe <john@yourdomain.com>",
"to": ["user@example.com"],
"subject": "Welcome to Our Platform",
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
"text": "Welcome! Thanks for signing up."
}'
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from": "John Doe <john@yourdomain.com>",
"to": ["user@example.com"],
"created_at": "2024-01-15T10:30:00.000Z"
}
With Template
curl -X POST https://api.unosend.co/emails \
-H "Authorization: Bearer un_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "hello@yourdomain.com",
"to": ["user@example.com"],
"subject": "Welcome to Acme!",
"template_id": "550e8400-e29b-41d4-a716-446655440000",
"template_data": {
"first_name": "John",
"company_name": "Acme Inc"
}
}'
Scheduled Email
curl -X POST https://api.unosend.co/emails \
-H "Authorization: Bearer un_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "hello@yourdomain.com",
"to": ["user@example.com"],
"subject": "Your weekly digest",
"html": "<h1>Weekly Digest</h1><p>Here is your weekly update...</p>",
"scheduled_for": "2024-01-20T09:00:00.000Z"
}'
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from": "hello@yourdomain.com",
"to": ["user@example.com"],
"scheduled_for": "2024-01-20T09:00:00.000Z",
"status": "scheduled",
"created_at": "2024-01-15T10:30:00.000Z"
}
List Emails
GET/v1/emails
Get a paginated list of sent emails.
Query Parameters
| Parameter | Type | Description |
|---|
limit | number | Max results to return (default: 10, max: 100) |
offset | number | Number of results to skip (default: 0) |
curl "https://api.unosend.co/emails?limit=10&offset=0" \
-H "Authorization: Bearer un_your_api_key"
Response
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from_email": "hello@yourdomain.com",
"from_name": "John Doe",
"to_emails": ["user@example.com"],
"subject": "Welcome to Our Platform",
"status": "sent",
"created_at": "2024-01-15T10:30:00.000Z",
"sent_at": "2024-01-15T10:30:01.000Z"
}
]
}
Get Email Details
GET/v1/emails/:id
curl https://api.unosend.co/emails/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer un_your_api_key"
Send Batch Emails
POST/v1/emails/batchNew
Send up to 100 emails in a single API request. Emails are processed in parallel for maximum throughput. Each email in the batch uses the same format as the single email endpoint.
Request Body
An array of email objects (1-100 items). Each object follows the same schema as POST /v1/emails.
curl -X POST https://api.unosend.co/emails/batch \
-H "Authorization: Bearer un_your_api_key" \
-H "Content-Type: application/json" \
-d '[
{
"from": "Team <team@yourdomain.com>",
"to": "user1@example.com",
"subject": "Welcome, User 1!",
"html": "<h1>Welcome!</h1>"
},
{
"from": "Team <team@yourdomain.com>",
"to": "user2@example.com",
"subject": "Welcome, User 2!",
"html": "<h1>Welcome!</h1>"
},
{
"from": "Team <team@yourdomain.com>",
"to": "user3@example.com",
"subject": "Welcome, User 3!",
"html": "<h1>Welcome!</h1>"
}
]'
Response
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"from": "Team <team@yourdomain.com>",
"to": ["user1@example.com"],
"created_at": "2024-01-15T10:30:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"from": "Team <team@yourdomain.com>",
"to": ["user2@example.com"],
"created_at": "2024-01-15T10:30:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"from": "Team <team@yourdomain.com>",
"to": ["user3@example.com"],
"created_at": "2024-01-15T10:30:00.000Z"
}
],
"success_count": 3,
"error_count": 0
}
Partial Failure Response
If some emails fail, the response includes both successful and failed emails:
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"from": "Team <team@yourdomain.com>",
"to": ["user1@example.com"],
"created_at": "2024-01-15T10:30:00.000Z"
},
{
"error": "Domain unverified.com not verified",
"index": 1
}
],
"success_count": 1,
"error_count": 1
}
The batch endpoint checks your remaining quota before processing. If you don’t have enough emails remaining, the entire batch will be rejected with a 402 error.
Get Click Statistics
GET/v1/emails/:id/clicksNew
Get detailed click tracking statistics for an email, including all tracked links and click counts.
curl https://api.unosend.co/emails/550e8400-e29b-41d4-a716-446655440000/clicks \
-H "Authorization: Bearer un_your_api_key"
Response
{
"email_id": "550e8400-e29b-41d4-a716-446655440000",
"clicked": true,
"first_clicked_at": "2024-01-15T12:30:00.000Z",
"total_clicks": 5,
"unique_links_clicked": 2,
"links": [
{
"url": "https://example.com/signup",
"clicks": 3,
"last_clicked_at": "2024-01-15T14:45:00.000Z"
},
{
"url": "https://example.com/docs",
"clicks": 2,
"last_clicked_at": "2024-01-15T13:20:00.000Z"
}
]
}
Email Status
| Status | Description |
|---|
queued | Email is queued for sending |
scheduled | Email is scheduled for future delivery |
sent | Email was sent successfully |
delivered | Email was delivered to recipient |
bounced | Email bounced |
failed | Email failed to send |
