Accounts
Email Accounts
Create, list, update, and reset inbox accounts for managed domains.
Important notes
Accounts can only be created for domains with status = active.
Account response shapes vary slightly by endpoint (some include user_id or is_default).
GET
/v2/domains/:domain/email-accounts
List by domain
List accounts scoped to a specific domain.
Request
Path params: domain
Query: user_id, limit, offset
curl -X GET "http://127.0.0.1:3000/v2/domains/customer.com/email-accounts?user_id=user_123&limit=50" \ -H "x-api-key: YOUR_API_KEY"
Response
{
"domain": { "domain": "customer.com", "status": "active" },
"items": [
{ "id": 1, "domain": "customer.com", "local_part": "support", "address": "support@customer.com" }
],
"limit": 50,
"offset": 0
}
POST
/v2/email-accounts/create
Create account
Creates a mailbox and returns the password once.
Request
{
"domain": "customer.com",
"local_part": "billing",
"display_name": "Billing",
"user_id": "user_123",
"password": "optional"
}
curl -X POST "http://127.0.0.1:3000/v2/email-accounts/create" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"customer.com","local_part":"billing","user_id":"user_123"}'
Response
{
"account": {
"id": 1,
"userId": "user_123",
"domain": "customer.com",
"local_part": "billing",
"address": "billing@customer.com",
"display_name": "Billing",
"status": "active",
"isDefault": true
},
"password": "generated-password",
"note": "Save this password now. It will not be shown again."
}
GET
/v2/email-accounts
List accounts
List accounts, optionally filtered by domain.
Request
Query: user_id, domain, limit, offset
curl -X GET "http://127.0.0.1:3000/v2/email-accounts?user_id=user_123&domain=customer.com" \ -H "x-api-key: YOUR_API_KEY"
Response
{
"items": [
{ "id": 1, "user_id": "user_123", "domain": "customer.com", "address": "billing@customer.com" }
],
"limit": 50,
"offset": 0
}
GET
/v2/email-accounts/:id
Get account
Fetch a single email account by id.
Request
Path params: id
Query: user_id
curl -X GET "http://127.0.0.1:3000/v2/email-accounts/42?user_id=user_123" \ -H "x-api-key: YOUR_API_KEY"
Response
{
"account": {
"id": 42,
"user_id": "user_123",
"domain": "customer.com",
"address": "billing@customer.com"
}
}
PUT
/v2/email-accounts/:id
Update account
Update display name and/or status.
Request
Path params: id
{
"user_id": "user_123",
"display_name": "Billing",
"status": "active"
}
curl -X PUT "http://127.0.0.1:3000/v2/email-accounts/42" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id":"user_123","status":"active"}'
Response
{
"account": {
"id": 42,
"domain": "customer.com",
"address": "billing@customer.com",
"status": "active"
}
}
POST
/v2/email-accounts/delete
Delete account
Deletes an email account by id.
Request
{
"id": 42,
"user_id": "user_123"
}
curl -X POST "http://127.0.0.1:3000/v2/email-accounts/delete" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":42,"user_id":"user_123"}'
Response
{ "ok": true, "deleted": { "id": 42, "address": "billing@customer.com" } }
POST
/v2/email-accounts/:id/password/reset
Reset password
Resets an account password and returns it once.
Request
{
"user_id": "user_123",
"password": "optional-new-password"
}
curl -X POST "http://127.0.0.1:3000/v2/email-accounts/42/password/reset" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id":"user_123"}'
Response
{
"account": {
"id": 42,
"domain": "customer.com",
"address": "billing@customer.com"
},
"password": "new-password",
"note": "Save this password now. It will not be shown again."
}