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.
Create an inbox
- Open Inbox and choose your Nitrosend-provided address, or a verified domain under Settings > Domains.
- 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.
- 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. For usage and paid storage upgrades, see Inbox storage.
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
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 for address-change limits and API access.
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
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
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:
{
"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
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:
{
"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
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
GET /v1/my/conversations/{id} includes attachment metadata on its messages:
{
"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
Agents work the queue over MCP with two tools:
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_spamA 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
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 to email.received.
Mutating requests take an Idempotency-Key header, so a retried request never sends twice:
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?"
}
}'