Skip to Content

Create a mailbox

Creates a mailbox with one endpoint and returns it with status 201; the caller gets an admin grant on it.

POST
/v1/mailboxes

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.

Authorization

apiKey
headerx-api-key<token>

Header Parameters

idempotency-key?string

Optional 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.

Match^[\s\S]{1,255}$

Request Body

application/json
  1. body
namespaceId?|null
endpoint*
name*string
Lengthlength <= 120
slug?string|null
metadata?|null

Response Body

Success

application/json
  1. response
id*MailboxId
Match^mbx_[0-9a-hjkmnp-tv-z]{16,24}$
kind*MailboxKind

Whether a mailbox belongs to one person or is shared with a team.

Value in"personal""shared"
owner*|null
namespaceId*|null
slug*string
name*string
status*MailboxStatus
Value in"active""paused"
primaryAddress*string|null
sendingStatus*|null
createdAt*string
description*string|null
metadata*
endpoints*array<||>
updatedAt*string
Example Request
import { 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"
});
Example Response
{
  "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"
}

Related documentation