Create a mailbox
Provision a real receiving mailbox — support@yourdomain.com — on a domain you have already verified.
Three consequences worth knowing before you call it:
- It changes how your domain's mail is routed. The first mailbox on a domain turns receiving on for that domain, so mail addressed there starts arriving at Sendly instead of wherever it went before.
- The domain must be verified. An unverified domain answers 409; creating a mailbox is not a way to skip DNS.
- Ten per project. The eleventh answers 409. Deleted mailboxes free their slot; failed ones never consumed one.
Retrying a failed provision with the same address reclaims the failed row rather than answering 409 — but only for the same project and the same domain.
quotaBytes is accepted by the schema and REFUSED with a 400. Quotas are not implemented, and the field is still parsed so that asking for one is an error rather than a silently dropped key.
Requires the mailboxes:write scope — Create and delete mailboxes on your verified domains.
BetterAuth session cookie. Used by the dashboard / browser clients. When present, the active project is taken from the x-project-id header.
In: cookie
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/mailboxes" \ -H "Content-Type: application/json" \ -d '{ "domainId": "8a0b02c3-fdd8-452e-bc6e-ef07a335ec7e", "localPart": "string" }'{
"success": true,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"address": "user@example.com",
"displayName": "string",
"status": "PROVISIONING",
"quotaBytes": 0,
"domainId": "8a0b02c3-fdd8-452e-bc6e-ef07a335ec7e",
"createdAt": "2019-08-24T14:15:22Z"
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}