Inbound Addresses API
Manage the email addresses where you receive inbound emails. Configure forwarding, webhooks, and auto-reply per address.
GET /v1/inbound/addresses
List all inbound addresses for your organization.
cURL
curl https://api.yoursend.dev/v1/inbound/addresses \
-H "Authorization: Bearer ys_live_..."Response
{
"addresses": [
{
"id": "2f4a3d16-...",
"address": "support@yourdomain.com",
"display_name": "Support Team",
"is_active": true,
"forward_to": [],
"webhook_url": null,
"auto_reply_enabled": false,
"created_at": "2026-03-20T03:29:54Z"
}
]
}POST /v1/inbound/addresses
Create a new inbound address. The domain part of the address must match your verified sending domain.
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Email address (e.g., support@yourdomain.com) |
display_name | string | No | Friendly display name |
forward_to | string[] | No | Array of email addresses to forward incoming mail to |
webhook_url | string | No | HTTPS URL to POST incoming email payloads to |
auto_reply_enabled | boolean | No | Enable auto-reply (default: false) |
auto_reply_subject | string | No | Subject line for auto-reply |
auto_reply_html | string | No | HTML body for auto-reply |
auto_reply_text | string | No | Plain text body for auto-reply |
cURL
curl -X POST https://api.yoursend.dev/v1/inbound/addresses \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"address": "support@yourdomain.com",
"display_name": "Support Team",
"forward_to": ["team@company.com"],
"webhook_url": "https://example.com/hooks/email",
"auto_reply_enabled": true,
"auto_reply_subject": "We received your email!",
"auto_reply_html": "<p>Thanks! We\'ll respond within 24 hours.</p>"
}'SDK
const address = await ys.inbound.addresses.create({
address: 'support@yourdomain.com',
display_name: 'Support Team',
forward_to: ['team@company.com'],
webhook_url: 'https://example.com/hooks/email',
});GET /v1/inbound/addresses/:id
Get a single inbound address by ID.
cURL
curl https://api.yoursend.dev/v1/inbound/addresses/2f4a3d16-... \
-H "Authorization: Bearer ys_live_..."PUT /v1/inbound/addresses/:id
Update an inbound address. Pass only the fields you want to change.
| Field | Description |
|---|---|
display_name | Update the display name |
is_active | Enable or disable the address |
forward_to | Update forwarding addresses |
webhook_url | Update webhook endpoint |
auto_reply_enabled, auto_reply_subject, auto_reply_html, auto_reply_text | Update auto-reply settings |
cURL
curl -X PUT https://api.yoursend.dev/v1/inbound/addresses/2f4a3d16-... \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{ "auto_reply_enabled": false, "forward_to": [] }'DELETE /v1/inbound/addresses/:id
Delete an inbound address. Existing emails will not be deleted.
cURL
curl -X DELETE https://api.yoursend.dev/v1/inbound/addresses/2f4a3d16-... \
-H "Authorization: Bearer ys_live_..."Address Object
| Field | Type | Description |
|---|---|---|
id | string | Unique address ID |
address | string | The email address |
display_name | string | null | Friendly name |
is_active | boolean | Whether the address is actively receiving |
forward_to | string[] | Forwarding destinations |
webhook_url | string | null | Webhook endpoint URL |
auto_reply_enabled | boolean | Auto-reply toggle |
created_at | string | ISO 8601 timestamp |