# Using the Agent Inbox {#using-the-agent-inbox}


Start from the **Inbox** page in your dashboard. Use a Nitrosend-provided address or your own domain for an inbox your agent and your team answer together. For what the inbox is and how the queue works, see [Agent Inbox](https://docs.nitrosend.com/concepts/agent-inbox.md).


## Create an inbox {#create-an-inbox}


1. Open **Inbox** and choose your Nitrosend-provided address, or a verified domain under **Settings > Domains**.
2. For your own domain, follow the delivery setup shown. Keep your current provider and forward a copy, or choose to receive mail in Nitrosend. Review and verify the delivery destination before changing DNS.
3. Choose the address (for example `support@`) and a sender name.

Mail lands in your queue once the delivery setup is ready. A Nitrosend-provided address does not need custom DNS.

For optional copies to an existing provider, see [Coexist](https://docs.nitrosend.com/guides/inbox-coexist.md).
For usage and paid storage upgrades, see [Inbox storage](https://docs.nitrosend.com/guides/inbox-storage.md).


## Change your sender name {#change-your-sender-name}


Open **Inbox**, choose **Manage inboxes**, and select the inbox. Edit **Sender
name** and choose **Save name**. The name appears on new emails and replies;
previously sent messages keep their original name.

Leave the name blank to use your company name, or the inbox address if no
company name is set. Your campaign sender name is separate.

Over REST, send `PATCH /v1/my/inboxes/{id}` with
`{ "inbox": { "display_name": "Support team" } }`. Names are trimmed and limited
to 255 characters; control characters are rejected. A blank or `null` value
clears the custom name.


## Change your Nitrosend address {#change-your-nitrosend-address}


Open **Inbox → Manage inboxes** and choose your Nitrosend address. You can edit
the part before `@`, or select **Change address name** to change your brand's part
of the domain. Both changes keep the same inbox and history. Old addresses keep
receiving mail; replies use the current address. Each named inbox keeps its own local part when the brand address name changes.

To change the name recipients see, edit **Sender name** separately. Past messages
keep their original sender name and address. See [Sending Domains](https://docs.nitrosend.com/guides/sending-domains.md#change-your-nitrosend-address)
for address-change limits and API access.


## Add another inbox {#add-another-inbox}


Open **Inbox**, choose **Add or manage inboxes**, then **New inbox**. Choose a receiving domain, enter the new email address and sender name, and create it. For a provider-forwarded inbox, finish its delivery setup and send a verification message.

If your included capacity is in use, open **Account > Billing > Inboxes**. Choose the number of additional inboxes, review the recurring price and approve payment. Return to Inbox to continue your saved draft. Creation never starts a purchase automatically.

Aliases are retired. Each new address is a separate inbox. Existing customer-added aliases become included inboxes with their old history preserved; old addresses retained after a rename keep receiving in the renamed inbox.

To archive an inbox, select it in **Add or manage inboxes** and choose **Archive inbox**. New mail and replies stop; messages and the address remain reserved. Restore it when capacity is available. Archive unused inboxes before reducing paid capacity or cancelling its renewal.


## Triage the queue {#triage-the-queue}


Open **Inbox** in the dashboard. Tabs split the queue by state: **Needs you**, **Agent ready**, **Handled**, **Quarantine**, and **All threads**.

The whole queue works from the keyboard:

| Key | Action |
|---|---|
| `j` / `k` | Move down / up the list |
| `Enter` | Open the thread |
| `e` | Mark handled |
| `r` | Reply to the open thread |
| `c` | Compose a new message |
| `Esc` | Close the thread |

Each thread shows the conversation timeline, the item's state, and the available actions: **Mark handled**, **Needs human**, **Release to agent**, and **Quarantine**. Virus-flagged mail never offers release to agent.


## Compose a new message {#compose-a-new-message}


Click **New message** (or press `c`). Choose the address to send from, add recipients (To, Cc, and Bcc all accept multiple addresses; paste a comma-separated list and it splits into recipients), write a subject and a plain-text body, and send. `Cmd+Enter` sends from the keyboard. Drafts survive closing the composer.

If the recipient already has an open conversation with that inbox, your message continues the existing thread.

Your connected agent can do the same with `nitro_inbox_action`:

```json
{
  "command": "compose",
  "inbox_id": 123,
  "to": ["maya@example.com"],
  "subject": "A quick question",
  "body": "Hello Maya, can we confirm the meeting time?",
  "idempotency_key": "meeting-question-1",
  "dry_run": true
}
```

Preview first, then send the same request with `dry_run: false` after approving
the message. `cc`, `bcc` and uploaded `attachment_refs` are optional. Reuse the
same key and message for retries; use a new key for a different sender,
recipient list or message. A successful send returns the conversation and
message IDs. Read the conversation with `nitro_inbox` before replying.


## Reply with your team copied {#reply-with-your-team-copied}


Open a thread and choose **Reply all** to include the sender and visible To/Cc participants. Your inbox's own addresses are excluded. Use **Cc** or **Bcc** to edit copies before sending. Hidden recipients from incoming mail are never carried into a reply.

For MCP, `send_reply` and `validate_reply` accept `reply_all: true`, `cc` and `bcc`. An explicit `cc` list replaces the suggested reply-all copies. The preview returns the resolved `recipients`; check those before sending. `send_reply_test` sends only to your chosen test recipients, never the real thread participants.

The REST reply body accepts the same options:

```json
{
  "reply": {
    "body": "Thanks, everyone. The report is ready.",
    "reply_all": true,
    "bcc": ["records@example.com"]
  }
}
```

Send it to `POST /v1/my/conversations/:id/reply` with an `Idempotency-Key`. Each recipient list supports up to 10 addresses. Each distinct recipient uses one email credit and counts toward your sending allowance. Retry with the same key and unchanged request; an accepted reply keeps its original recipients even if more mail arrives on the thread.


## View a message's source {#view-a-messages-source}


Hover any message in a thread and click the source icon to see the full stored headers, authentication results, and raw text and HTML content.


## Read attachment availability {#read-attachment-availability}


`GET /v1/my/conversations/{id}` includes attachment metadata on its messages:

```json
{
  "id": 311,
  "filename": "travel-details.pdf",
  "scan_status": "clean",
  "downloadable": true,
  "download_requires_confirmation": false
}
```

The conversation response uses `scan_status`, not a `scanned` boolean:

| `scan_status` | Meaning |
|---|---|
| `clean` | The provider or configured scanner returned a clean verdict. |
| `not_scanned` | No scan verdict covered the file. Downloads require `acknowledge_unscanned=true`. |
| `pending` | Attachment processing has not finished. |
| `infected` | A threat was reported; the file is unavailable. |
| `failed` | Processing did not return a usable verdict; the file is unavailable. |

Use `downloadable` to decide whether a file is available, since its stored bytes
may be unavailable even when a clean verdict exists. `availability_reason`
explains a restriction. A clean SES verdict applies to the received message;
it does not establish that Nitrosend ran a separate scan on each attachment.

The `email.received` webhook lists every attachment, available or not, with
these same fields. It also carries a derived `scanned` boolean, `true` only for
`clean`. That field is not part of the conversation attachment response. A
missing field in one response must not be interpreted as a scan failure.


## Connect your agent {#connect-your-agent}


Agents work the queue over MCP with two tools:

```text
nitro_inbox         list_queue | get_item | list_mailbox | get_thread | get_thread_page | get_message_body | validate_reply
nitro_inbox_action  send_reply | send_reply_test | mark_handled | request_human | release_to_agent | mark_quarantine | classify_spam
```

A typical loop: `list_queue` with `state: "agent_ready"`, `get_item` for the thread, follow `get_thread_page` or `get_message_body` when the response provides those continuation calls, `validate_reply` to check the draft, `send_reply_test` to verify an explicit test recipient when needed, `send_reply` to answer, and `request_human` for anything the agent should not decide alone. An accepted `send_reply` marks its item handled on its own; use `mark_handled` for items you close without replying.

`send_reply` answers any item outside quarantine. Needs you holds mail a person should look at first, which is why an unattended loop lists `agent_ready`; when you drive the agent yourself, it can answer a Needs you item without releasing it. Quarantined mail has to leave quarantine before anyone replies.

`list_queue` and `list_mailbox` return compact rows by default (id, state, reason codes, sender, subject, timing) and take `view: "full"` for previews and contact context. The queue filters by `state`, `inbox_id`, `reason_code`, `sender`, `query`, `since`, and `sort`; page 1 carries the state counts. Reads that will not reply can pass `purpose: "read"` to `get_thread` and skip the reply context. When a read returns a `brand_context_ref`, pass it on the next read so the brand packet is reused rather than re-sent.

Sender rules (`set_sender_policy`, or `POST /v1/my/inboxes/:id/sender_policy`) take three decisions: `allow` skips the provider spam gate for that sender or domain, `block` quarantines it, and `handle` projects its mail straight to `handled` with the reason `sender_auto_handled`, which is how notification senders (CI, OTP mailers, marketplace bots) stay out of the queue for good. Like `allow`, `handle` overrides the provider spam verdict for that sender; a virus verdict or an inactive inbox still quarantines regardless of the rule. Separately, a `Reply-To` that differs from `From` but shares its registrable domain on an authenticated message is recorded as `reply_to_mismatch_aligned` and no longer sends ordinary list mail to a human; a cross-domain `Reply-To` still does.

Triage verbs (`mark_handled`, `request_human`, `release_to_agent`, `mark_quarantine`, `classify_spam`) act on one item with `action_item_id`, on up to 100 with `action_item_ids`, or on a `filter` (the same keys as `list_queue`) with `expected_count` set to the total the listing reported; a filter that selects more than 100 items is refused, so narrow it or work through it in pages. A batch returns `updated` ids with their new state and `skipped` ids with a reason, never item bodies; if the filtered selection changed since it was listed, the call is refused with the live count so nothing acts on mail you have not seen.


## REST API {#rest-api}


Everything the dashboard does is available over REST:

| Endpoint | Purpose |
|---|---|
| `GET /v1/my/inboxes/capacity?quantity=43` | Read account-wide capacity and the server quote for 43 additional inboxes |
| `POST /v1/my/inboxes` | Create an inbox within confirmed capacity; no automatic purchase |
| `GET /v1/my/inboxes/:id` | Read an inbox's name, addresses and settings |
| `PATCH /v1/my/inboxes/:id` | Edit `inbox.display_name` or set `inbox.status` to `active` / `archived` |
| `GET /v1/my/inbox_action_items` | List the queue (`state`, `inbox_id`, `reason_code`, `sender`, `query`, `since`, `sort` filters) |
| `POST /v1/my/inbox_action_items/:id/act` | Apply a verb (`mark_handled`, `request_human`, `release_to_agent`, `mark_quarantine`) |
| `POST /v1/my/inbox_action_items/act` | Apply one verb to many items (`action_item_ids`, or `filter` + `expected_count`; max 100) |
| `GET /v1/my/conversations` | List threads (`mailbox=true`, `inbox_id`, `query`) |
| `GET /v1/my/conversations/:id` | Thread with messages |
| `POST /v1/my/conversations` | Compose a new message (`inbox_id`, `to[]`, `cc[]`, `bcc[]`, `subject`, `body`) |
| `POST /v1/my/conversations/:id/reply` | Reply to a thread |
| `GET /v1/my/conversations/:id/messages/:message_id/source` | Full headers and source for one message |

To have new mail pushed to your own system as it arrives, subscribe a
[webhook](https://docs.nitrosend.com/integrations/webhooks.md#replies) to `email.received`.

Mutating requests take an `Idempotency-Key` header, so a retried request never sends twice:

```bash
curl -X POST https://api.nitrosend.com/v1/my/conversations \
  -H "Authorization: Bearer nskey_live_..." \
  -H "Idempotency-Key: 4f7c1e2a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "inbox_id": 12,
      "to": ["dana@example.com"],
      "subject": "Kicking off your onboarding",
      "body": "Hi Dana, welcome aboard. Want me to walk you through your first campaign this week?"
    }
  }'
```
