InboxNest API

The InboxNest REST API lets a script or AI agent do what the MCP tools do, plus create addresses, receive webhooks and send app email, with one API key. Everything is JSON over HTTPS at https://tryinboxnest.com/api/v1/, and the full description is in openapi.json.

New to InboxNest and AI? Give your AI agent a support inbox explains the safety model first.

Quickstart

1. In InboxNest, open Settings → API keys and create a key. Tick only the permissions it needs. Copy the key: you won’t see it again.
2. Call the API with the key as a Bearer token.

export INBOXNEST_KEY=inbx_live_…

# Who am I, and what may this key do?
curl https://tryinboxnest.com/api/v1/me -H "Authorization: Bearer $INBOXNEST_KEY"

# Unread conversations in the inbox
curl "https://tryinboxnest.com/api/v1/conversations?unread=true&limit=10" -H "Authorization: Bearer $INBOXNEST_KEY"

# Read one, with its messages
curl https://tryinboxnest.com/api/v1/conversations/1234 -H "Authorization: Bearer $INBOXNEST_KEY"

# Reply (needs mail:send and "Allow AI apps to send replies")
curl -X POST https://tryinboxnest.com/api/v1/conversations/1234/reply \
  -H "Authorization: Bearer $INBOXNEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-1234-1" \
  -d '{"body_text": "Thanks! Your order ships tomorrow."}'

Authentication and scopes

Send the key in the Authorization header: Authorization: Bearer inbx_live_…. A missing, invalid, expired or revoked key gets 401. The same key also works as a Bearer token on the MCP server at https://tryinboxnest.com/mcp, with the same permissions and limits.

Each key carries scopes:

• inbox:read: read domains, addresses, conversations and drafts (always on).
• drafts:write: save and delete reply drafts.
• inbox:write: mark read, flag for follow-up, move to Spam or Trash.
• mail:send: reply on existing conversations.
• mail:send_new: start new conversations (needs approval).
• addresses:write: create and remove addresses.
• webhooks:write: manage webhook endpoints.
• mail:transactional: send app emails (needs approval).

A call without the scope it needs gets 403 insufficient_scope, naming the scope. A key can be limited to some domains: anything on other domains then returns 404, as if it did not exist. Sending replies and new conversations also needs Allow AI apps to send replies turned on in Settings; otherwise you get 403 sending_disabled.

Errors

Every error uses the same shape. code is stable and safe to branch on; message is for people. Every response, success or error, has an X-Request-Id header: include it if you contact support.

{
  "error": {
    "code": "rate_limited",
    "message": "This API key has sent 30 replies in the last hour, which is its limit.",
    "retry_after": 1260,
    "scope": "key"
  }
}

Common codes: unauthorized (401), insufficient_scope, sending_disabled, key_sending_paused and account_inactive (403), not_found (404), idempotency_conflict (409), invalid_request (422), rate_limited (429), and agent_stream_not_configured or app_stream_not_configured (503).

Pagination

List endpoints take limit (1 to 100, default 25) and return {"data": [...], "next_cursor": "..."}. Pass next_cursor back as cursor to get the next page. When next_cursor is null you have everything.

Idempotency

Every send (POST /conversations/{id}/reply, POST /conversations, POST /drafts/{id}/send, POST /emails, POST /emails/batch) requires an Idempotency-Key header. Other POSTs accept one. Use a unique value per action, such as a UUID or your own job id.

• Same key and same body within 24 hours: you get the original response again (with Idempotent-Replayed: true) and nothing is sent twice.
• Same key, different body: 409 idempotency_conflict.
• Refusals (4xx) are remembered too. Server errors (5xx) and 429 are not, so you can retry those with the same key.

Rate limits

Each key may make 120 requests a minute, of which 20 may be writes. Sending has more limits, all checked on every send, and the strictest wins:

• Per key: 30 replies an hour and 200 a day; 10 new conversations an hour and 30 a day.
• Per account: InboxNest’s normal sending limits (burst limits per minute, daily limits, and lower limits for new domains).
• New conversations and app emails: a daily limit that starts low and grows (see the safety model).

Every limit answers 429 with a Retry-After header (seconds) and error.scope saying which limit was hit: key, account, domain, address, new_conversation, transactional_daily or transactional_allowance.

API guides