AutoSend Email API
Send transactional emails, manage contacts, and use templates via REST API.
Using JavaScript/TypeScript? See the SDK Guide for TypeScript examples with the autosendjs package.Reference: API Guide | Official API Reference
Prerequisites
Complete these steps before using the API:
- Create Account — Sign up at autosend.com
- Add Domain — Settings → Domains → Add Domain → Select AWS region (docs)
- Configure DNS — Copy the generated records (DKIM, SPF, DMARC) to your DNS provider
- Verify Domain — Click "Verify Ownership" and wait for status to turn green (5-30 min)
- Get API Key — Settings → API Keys → Generate API Key (docs)
- Set Environment Variable —
export AUTOSEND_API_KEY=as_your_key_here
Authentication
All requests require a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEYBase URL: https://api.autosend.com/v1
All POST/PUT requests must include Content-Type: application/json.
Email Operations
Send Email
POST /v1/mails/send
Send a single transactional email.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | object | Yes | Sender — {"email": "...", "name": "..."} |
to | object | Yes | Recipient — {"email": "...", "name": "..."} |
subject | string | Yes | Email subject line |
html | string | No | HTML body |
text | string | No | Plain text body |
templateId | string | No | Template ID (replaces html/text) |
dynamicData | object | No | Template variable substitutions |
cc | array | No | CC recipients — [{"email": "...", "name": "..."}] |
bcc | array | No | BCC recipients — [{"email": "...", "name": "..."}] |
replyTo | object | No | Reply-to address — {"email": "...", "name": "..."} |
attachments | array | No | File attachments — [{"filename": "...", "content": "..."}] |
Response:
{
"success": true,
"data": { "emailId": "email_abc123" }
}Bulk Send
POST /v1/mails/bulk
Send emails to multiple recipients with a shared sender, subject, and optional template.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | object | Yes | Shared sender — {"email": "...", "name": "..."} |
subject | string | No | Shared subject (required unless template provides it) |
html | string | No | Shared HTML body |
text | string | No | Shared plain text body |
templateId | string | No | Template ID for templated emails |
dynamicData | object | No | Shared default template variables |
recipients | array | Yes | Array of recipient objects (max 100) |
Recipient object:
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Recipient email address |
name | string | No | Recipient display name |
dynamicData | object | No | Per-recipient variables (overrides shared) |
cc | array | No | Per-recipient CC |
bcc | array | No | Per-recipient BCC |
Limit: Maximum 100 recipients per bulk request.
Response:
{
"success": true,
"data": {
"batchId": "batch_abc123",
"totalRecipients": 2,
"successCount": 2,
"failedCount": 0
}
}Templates
POST /v1/mails/send with templateId
Send templated emails by passing a templateId and dynamicData instead of (or alongside) html/text.
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Template identifier |
dynamicData | object | No | Key-value pairs for template variables |
Common template IDs:
| Template | ID | Typical Variables |
|---|---|---|
| Order Confirmation | tmpl_order_confirmation | orderNumber, customerName, orderTotal, estimatedDelivery |
| Welcome Email | tmpl_welcome | firstName, activationLink, supportEmail |
| Password Reset | tmpl_password_reset | resetLink, expiresIn |
Templates also work with bulk send — pass templateId and dynamicData in the bulk request body.
Contact Management
Create Contact
POST /v1/contacts
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Contact email address |
firstName | string | No | Contact first name |
lastName | string | No | Contact last name |
userId | string | No | External user ID |
listIds | array | No | Lists to add contact to — ["list_abc", "list_xyz"] |
customFields | object | No | Custom field values |
Response:
{
"success": true,
"data": {
"id": "contact_abc123",
"email": "user@example.com",
"firstName": "Jane",
"lastName": "Smith",
"listIds": ["list_abc"],
"customFields": {},
"createdAt": "2025-01-15T00:00:00Z",
"updatedAt": "2025-01-15T00:00:00Z"
}
}Get Contact
GET /v1/contacts/:id
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact ID (path parameter) |
Response: Returns the contact object (same shape as Create Contact response).
Upsert Contact
POST /v1/contacts/email
Create or update a contact by email address. If a contact with the given email exists, it is updated; otherwise a new contact is created.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Contact email address |
firstName | string | No | Contact first name |
lastName | string | No | Contact last name |
userId | string | No | External user ID |
listIds | array | No | Lists to add contact to |
customFields | object | No | Custom field values |
Response: Returns the contact object (same shape as Create Contact response).
Delete Contact
DELETE /v1/contacts/:id
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact ID (path parameter) |
Response:
{
"success": true
}Error Handling
All errors return JSON with an error object:
{
"success": false,
"error": {
"message": "The 'to' field is required",
"code": "VALIDATION_FAILED",
"details": []
}
}| Status | Code | Description |
|---|---|---|
400 | VALIDATION_FAILED | Bad request — missing or invalid parameters |
401 | UNAUTHORIZED | Invalid or missing API key |
402 | PAYMENT_REQUIRED | Plan upgrade needed |
403 | FORBIDDEN | Insufficient permissions |
404 | NOT_FOUND | Resource not found |
429 | RATE_LIMIT_EXCEEDED | Too many requests — retry with backoff |
500 | SERVER_ERROR | Internal server error |