API Reference
Emails
Send transactional and marketing emails through the Unosend API. This endpoint supports HTML, plain text, templates, attachments, and scheduled sending.
POST
/v1/emailsSend an Email
Send an email to one or more recipients. Returns the email ID for tracking.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | Required | Sender email (e.g., "John Doe <john@domain.com>") |
to | string | string[] | Required | Recipient email address(es) |
subject | string | Required | Email subject line |
html | string | Optional | HTML content of the email |
text | string | Optional | Plain text content |
cc | string | string[] | Optional | CC recipients |
bcc | string | string[] | Optional | BCC recipients |
reply_to | string | Optional | Reply-to address |
template_id | string | Optional | Template ID (instead of html/text) |
template_data | object | Optional | Variables for template rendering |
scheduled_for | string | Optional | ISO 8601 datetime for scheduled sending |
tags | object | Optional | Custom tags for analytics |
Basic Example
cURL
curl -X POST https://www.unosend.co/api/v1/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
200 OK
{
"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
curl -X POST https://www.unosend.co/api/v1/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
curl -X POST https://www.unosend.co/api/v1/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
200 OK
{
"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"
}GET
/v1/emailsList 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
curl "https://www.unosend.co/api/v1/emails?limit=10&offset=0" \
-H "Authorization: Bearer un_your_api_key"Response
200 OK
{
"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
/v1/emails/:idGet Email Details
cURL
curl https://www.unosend.co/api/v1/emails/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer un_your_api_key"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 |