Setup
To receive inbound emails, you need to:
- Add and verify your domain in the Unosend dashboard
- Enable “Receive Inbound Emails” on the domain settings
- Update your domain’s MX records to point to our inbound servers
- (Optional) Configure a webhook URL to receive real-time notifications
MX Records
Add these MX records to your domain:
Priority: 10
Host: @
Value: inbound.unosend.co
List Inbound Emails
GET/v1/inbound
Retrieve a list of inbound emails received at your domains.
Query Parameters
| Parameter | Type | Description |
|---|
limit | integer | Number of emails to return (default: 50, max: 100) |
offset | integer | Number of emails to skip for pagination |
status | string | Filter by status: received, processed, failed |
curl https://www.unosend.co/api/v1/inbound \
-H "Authorization: Bearer un_your_api_key"
Response
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from": "sender@example.com",
"from_name": "John Doe",
"to": ["hello@yourdomain.com"],
"cc": null,
"subject": "Hello from the API",
"has_html": true,
"has_text": true,
"attachment_count": 2,
"received_at": "2024-01-15T10:30:00.000Z"
}
]
}
Get Inbound Email
GET/v1/inbound/:id
Retrieve the full content of an inbound email including HTML, text, and attachments.
curl https://www.unosend.co/api/v1/inbound/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer un_your_api_key"
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from": "sender@example.com",
"from_name": "John Doe",
"to": ["hello@yourdomain.com"],
"cc": null,
"subject": "Hello from the API",
"html": "<html><body><h1>Hello!</h1></body></html>",
"text": "Hello!",
"attachments": [
{
"id": "att_123",
"filename": "document.pdf",
"contentType": "application/pdf",
"size": 102400
}
],
"received_at": "2024-01-15T10:30:00.000Z"
}
Webhooks
Configure a webhook to receive real-time notifications when emails arrive. Create a webhook endpoint that subscribes to the email.received event.
Webhook Payload
{
"type": "email.received",
"data": {
"inbound_email_id": "550e8400-e29b-41d4-a716-446655440000",
"from": "sender@example.com",
"from_name": "John Doe",
"to": ["hello@yourdomain.com"],
"cc": null,
"subject": "Hello from the API",
"has_html": true,
"has_text": true,
"attachment_count": 2
},
"created_at": "2024-01-15T10:30:00.000Z"
}
The webhook only contains metadata. Use the inbound_email_id to fetch the full email content via the API if needed.
List Attachments
GET/v1/inbound/:id/attachments
Retrieve a list of attachments for an inbound email with signed download URLs that expire in 1 hour.
curl https://www.unosend.co/api/v1/inbound/550e8400-e29b-41d4-a716-446655440000/attachments \
-H "Authorization: Bearer un_your_api_key"
Response
{
"data": [
{
"id": "att_550e8400-e29b-41d4-a716",
"filename": "document.pdf",
"content_type": "application/pdf",
"content_disposition": "attachment",
"content_id": null,
"size": 102400,
"download_url": "https://supabase.co/storage/...",
"expires_at": "2024-01-15T11:30:00.000Z"
},
{
"id": "att_660e8400-e29b-41d4-a717",
"filename": "logo.png",
"content_type": "image/png",
"content_disposition": "inline",
"content_id": "img001",
"size": 24567,
"download_url": "https://supabase.co/storage/...",
"expires_at": "2024-01-15T11:30:00.000Z"
}
]
}
Download URLs expire after 1 hour. Request new URLs if needed.
Reply to Email
POST/v1/inbound/:id/reply
Send a reply to an inbound email. The reply is automatically threaded with proper In-Reply-To and References headers.
Request Body
| Field | Type | Description |
|---|
html | string | HTML content of the reply (optional if text provided) |
text | string | Plain text content of the reply (optional if html provided) |
curl -X POST https://www.unosend.co/api/v1/inbound/550e8400-e29b-41d4-a716-446655440000/reply \
-H "Authorization: Bearer un_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"html": "<p>Thank you for your email!</p>",
"text": "Thank you for your email!"
}'
Response
{
"success": true,
"messageId": "msg_abc123...",
"emailId": "email_xyz789..."
}
Delete Inbound Email
DELETE/v1/inbound/:id
Permanently delete an inbound email and its attachments. This action cannot be undone.
curl -X DELETE https://www.unosend.co/api/v1/inbound/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer un_your_api_key"
Response
{
"deleted": true,
"id": "550e8400-e29b-41d4-a716-446655440000"
}
Spam Filtering
All inbound emails are automatically scanned for spam. The response includes:
| Field | Description |
|---|
spam_status | clean, spam, or suspicious |
spam_score | Numeric score (higher = more likely spam) |
spf_result | SPF verification result (pass, fail, neutral) |
dkim_result | DKIM verification result |
dmarc_result | DMARC verification result |
