---
title: "Add an endpoint to a mailbox"
method: POST
path: "/v1/mailboxes/{id}/endpoints"
tags: ["Mailboxes"]
---

# Add an endpoint to a mailbox

`POST /v1/mailboxes/{id}/endpoints`

## Request

- Base URL: `https://api.samva.dev`
- URL: `https://api.samva.dev/v1/mailboxes/{id}/endpoints`
- Auth: API key in header `x-api-key`

Adds an endpoint to a mailbox and returns the mailbox with status 201. It follows the same rules as the endpoint of a new mailbox: an email address must be under the organization's Samva-hosted mail domain or a verified domain with receiving enabled, a phone number must be one the organization connected on that channel, and no mailbox may already hold it (409). Messages sent to it reach the mailbox from now on. It becomes the default on its channel only when the mailbox has no endpoint there yet.

## Path parameters

- `id` string, required

## Request body

- CreateMailboxEndpointPayload
  - `channel` 'email', required: The channel an endpoint, thread, or message belongs to.
  - `address` string, required
  - `displayName` string, nullable

## Response `201`

Success

- Mailbox
  - `id` string, required
  - `namespaceId` string, required
  - `slug` string, required
  - `name` string, required
  - `status` 'active' | 'paused', required
  - `primaryAddress` string, nullable, required
  - `createdAt` string, required
  - `description` string, nullable, required
  - `metadata` MailboxMetadata, required
  - `endpoints` MailboxEndpoint[], required
    - `id` string, required
    - `address` string, required
    - `displayName` string, nullable, required
    - `default` boolean, required
    - `channel` 'email', required
    - `source` 'samvaHosted' | 'verifiedDomain', required
    - `domainId` string, nullable, required
  - `updatedAt` string, required

## Other responses

- `401`: UnauthorizedError
- `403`: FlagDisabledError | ForbiddenError
- `404`: ResourceNotFoundError
- `409`: ConflictError
- `422`: ValidationError
- `500`: InternalError
- `504`: GatewayTimeoutError

---

[API](https://skmtc.dev/samva/apis/samva-api.md) · [All operations](https://skmtc.dev/samva/apis/samva-api/llms.txt) · [OpenAPI document](https://skmtc.dev/samva/apis/samva-api/revisions/a99408542cc3?raw)