Inbound Emails API
List, read, update, reply to, and delete inbound emails received at your configured addresses.
GET /v1/inbound
List all inbound emails for your organization, newest first.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Results per page (max 100) |
offset | integer | 0 | Offset for pagination |
status | string | - | Filter by status: new, read, replied, archived |
cURL
curl https://api.yoursend.dev/v1/inbound?status=new \
-H "Authorization: Bearer ys_live_..."Response
{
"emails": [
{
"id": "50d4a4d6-...",
"from_address": "customer@gmail.com",
"to_address": "support@yourdomain.com",
"subject": "Need help with my order",
"status": "new",
"spam_verdict": "PASS",
"virus_verdict": "PASS",
"spf_verdict": "PASS",
"dkim_verdict": "PASS",
"dmarc_verdict": "PASS",
"address_id": "2f4a3d16-...",
"created_at": "2026-03-20T04:01:45Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}GET /v1/inbound/:id
Get a single inbound email by ID, including full content and headers.
cURL
curl https://api.yoursend.dev/v1/inbound/50d4a4d6-... \
-H "Authorization: Bearer ys_live_..."PUT /v1/inbound/:id
Update an email's status, assignment, or notes.
| Field | Type | Description |
|---|---|---|
status | string | new | read | replied | archived |
assigned_to | string | User ID or name to assign the email to |
notes | string | Internal notes about the email |
cURL
curl -X PUT https://api.yoursend.dev/v1/inbound/50d4a4d6-... \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{ "status": "read", "notes": "Customer asking about order #1234" }'POST /v1/inbound/:id/reply
Send a reply to an inbound email. The reply is sent from the inbound address that received the original email.
| Field | Type | Required | Description |
|---|---|---|---|
html | string | * | HTML body of the reply (* either html or text required) |
text | string | * | Plain text body of the reply |
subject | string | No | Subject line (defaults to "Re: [original subject]") |
cURL
curl -X POST https://api.yoursend.dev/v1/inbound/50d4a4d6-.../reply \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"html": "<p>Thanks for reaching out! We\'ll look into this right away.</p>",
"subject": "Re: Need help with my order"
}'SDK
await ys.inbound.reply('50d4a4d6-...', {
html: '<p>Thanks for reaching out!</p>',
});GET /v1/inbound/:id/replies
List all replies sent for an inbound email.
cURL
curl https://api.yoursend.dev/v1/inbound/50d4a4d6-.../replies \
-H "Authorization: Bearer ys_live_..."Response
{
"replies": [
{
"id": "abc123-...",
"from_address": "support@yourdomain.com",
"to_address": "customer@gmail.com",
"subject": "Re: Need help with my order",
"html": "<p>Thanks for reaching out!</p>",
"ses_message_id": "010f019d...",
"created_at": "2026-03-20T05:00:00Z"
}
]
}DELETE /v1/inbound/:id
Permanently delete an inbound email.
cURL
curl -X DELETE https://api.yoursend.dev/v1/inbound/50d4a4d6-... \
-H "Authorization: Bearer ys_live_..."Email Object
Full shape of an inbound email object:
| Field | Type | Description |
|---|---|---|
id | string | Unique email ID |
from_address | string | Sender email address |
to_address | string | Recipient inbound address |
subject | string | Email subject line |
status | string | new | read | replied | archived |
address_id | string | ID of the matched inbound address |
assigned_to | string | null | Assigned team member |
notes | string | null | Internal notes |
spam_verdict | string | PASS or FAIL |
virus_verdict | string | PASS or FAIL |
spf_verdict | string | PASS, FAIL, or NONE |
dkim_verdict | string | PASS, FAIL, or NONE |
dmarc_verdict | string | PASS, FAIL, or NONE |
raw_content | string | Full raw email content (MIME) |
created_at | string | ISO 8601 timestamp |