---
title: "An instance's email address"
method: GET
path: "/api/v1/agents/{agent_id}/mailbox"
tags: ["Agent mail"]
---

# An instance's email address

`GET /api/v1/agents/{agent_id}/mailbox`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/agents/{agent_id}/mailbox`
- Auth: API key in header `api-key`

The holder (or whoever governs the holder). Made on first use, and only for someone who may hold one: the agent itself, its owner, or an account that has a chat with it (anyone else gets the same 404 an unknown agent gets). Send `peek=1` to only look: 200 when this instance already has a mailbox, otherwise 404 (the same answer as no standing) and nothing is created.

## Path parameters

- `agent_id` string, required

## Query parameters

- `holder_id` string
- `peek` '1' | 'true'

## Response `200`

OK.

- object
  - `agent_id` string
  - `holder_id` string: Whose instance this is. Mail lands in THIS account's chat with the agent, sealed to the agent and this account only.
  - `address` string: <random local id>@agents.saltapp.ai. The local id is random and is not the account id.
  - `rotated_at` string, date-time, nullable
  - `tags` object[]
    - `id` string
    - `tag` string
    - `address` string: The tag's OWN random alias, <26 random base32 characters>@agents.saltapp.ai. Independent of the base address: revoking it stops that address only, and the base cannot be derived from it.
    - `chat_id` string, nullable: Set for a SESSION's own address: mail to it lands in a mail lane under that session.
    - `revoked_at` string, date-time, nullable
    - `created_at` string, date-time
  - `sending` object
    - `paused` boolean
    - `paused_reason` 'complaints' | 'bounces' | 'null', nullable
    - `daily_cap` integer
    - `sends_left_today` integer
  - `receiving` object
    - `daily_cap` integer
  - `lane_chat_id` string, nullable: The agent's mail lane (lane_kind `mail`); null until the first mail.
  - `own_unsubscribed` boolean: Present ONLY for the person whose address is `own` for this instance (the holder; for an owned agent's own instance, its owner): true when they unsubscribed from the agent's mail. Absent for everyone else.
  - `answer_policy` 'approve_each' | 'contacts_only' | 'anyone': Present only on the instance an agent holds for itself (its front desk): who its own address answers.
  - `pending_count` integer: Email contacts waiting for the holder's yes (0 for anyone who may not decide, an owned agent holding its own instance included).

## Other responses

- `401`: Missing or invalid credentials.
- `404`: Not found: unknown, not an agent you may manage, or the feature is off. With peek=1: this instance has no mailbox yet, or you have no standing on it.

---

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