Create a mailbox
Creates a mailbox with one endpoint and returns it with status 201; the caller gets an admin grant on it.
Creates a mailbox with one endpoint and returns it with status 201; the caller gets an admin grant on it. An email endpoint's address must be under the organization's Samva-hosted mail domain or a verified domain with receiving enabled, and the mailbox sends from it once its sendingStatus is ready. Hosted addresses return pending while sending setup completes. A phone endpoint's address is a number the organization connected on that channel, in E.164 form. The slug defaults to the address's local part, or a phone number's digits. Pass slug when that is taken or not a valid slug. The mailbox receives mail from now on; mail that arrived earlier is not added to it. Pass Idempotency-Key to retry safely: the same key and body return the original mailbox in its current state; a changed body returns 409. Conflicts if the address or slug is already in use. Returns 402 when the organization is at its plan's mailbox allowance or at its mailbox storage allowance; incoming mail is still received past the storage allowance.
apiKeyx-api-key<token>idempotency-key?stringOptional key that makes mailbox creation idempotent for the calling key or member. The same key and body return the original mailbox in its current state. A different body with the same key returns 409. Keep the key after a lost response; it remains bound for the mailbox's lifetime.
^[\s\S]{1,255}$application/json- body
namespaceId?|nullendpoint*name*stringlength <= 120slug?string|nullmetadata?|nullSuccess
application/json- response
id*MailboxId^mbx_[0-9a-hjkmnp-tv-z]{16,24}$kind*MailboxKindWhether a mailbox belongs to one person or is shared with a team.
"personal""shared"owner*|nullnamespaceId*|nullslug*stringname*stringstatus*MailboxStatus"active""paused"primaryAddress*string|nullsendingStatus*|nullcreatedAt*stringdescription*string|nullmetadata*endpoints*array<||>updatedAt*stringimport { createClient } from "samva";
const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const result = await samva.mailboxes.create({
"endpoint": {
"channel": "sms",
"address": "example"
},
"name": "example"
});{
"id": "string",
"kind": "personal",
"owner": "string",
"namespaceId": "string",
"slug": "string",
"name": "string",
"status": "active",
"primaryAddress": "string",
"sendingStatus": "pending",
"createdAt": "string",
"description": "string",
"metadata": {
"property1": "string",
"property2": "string"
},
"endpoints": [
{
"id": "string",
"address": "string",
"displayName": "string",
"default": true,
"channel": "email",
"source": "samvaHosted",
"domainId": "string",
"sendingStatus": "pending"
}
],
"updatedAt": "string"
}