Inboxes

See Inboxes for how they work. These endpoints need a full-access API key. Everything is scoped to your organization; IDs from another organization return 404. Lists are paginated and newest first.

#The inbox object

{
  "object": "inbox",
  "id": "5c0d1d9e-6a3b-4f55-8d7a-0e2d4a0b7f10",
  "name": "Support",
  "address": "[email protected]",
  "enabled": true,
  "created_at": "2026-10-11T08:00:00Z",
  "updated_at": "2026-10-11T08:00:00Z"
}

#Create an inbox

POST /inboxes

curl -X POST https://api.usend.et/inboxes \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support", "address": "[email protected]" }'

Returns 422 when the domain is not verified or does not receive, and 409 when the address already has an inbox.

#List, get, update and delete

• GET /inboxes
• GET /inboxes/{id}
• PATCH /inboxes/{id} with name and/or enabled
• DELETE /inboxes/{id}: removes the inbox with its threads, labels and drafts. The received mail stays under /inbound/emails.

#Labels

Labels belong to one inbox (at most 50).

• POST /inboxes/{id}/labels with name and optional color
• GET /inboxes/{id}/labels
• GET, PATCH and DELETE /inboxes/{id}/labels/{label_id}

#Threads

GET /inboxes/{id}/threads

{
  "object": "thread",
  "id": "f0a1b2c3-1111-4222-8333-444455556666",
  "inbox_id": "5c0d1d9e-6a3b-4f55-8d7a-0e2d4a0b7f10",
  "subject": "Question about my order",
  "folder": "inbox",
  "assignee_user_id": null,
  "labels": [{ "id": "8a1f0c52-0000-4000-8000-000000000001", "name": "Billing", "color": "" }],
  "snippet": "Hi, where is order #1042?",
  "message_count": 2,
  "unread_count": 1,
  "last_message_at": "2026-10-11T08:30:12Z",
  "created_at": "2026-10-11T08:30:12Z"
}

GET /inboxes/{id}/threads/{thread_id} returns one thread. DELETE removes it permanently.

PATCH /inboxes/{id}/threads/{thread_id} updates any of:

#Messages

• GET /inboxes/{id}/threads/{thread_id}/emails lists the messages of a thread.
• GET /inboxes/{id}/threads/{thread_id}/emails/{email_id} returns one with html, text, headers and attachments. Download an attachment at /inbound/emails/{inbound_email_id}/attachments/{attachment_id}.

direction is inbound for received messages and outbound for ones sent from the inbox.

#Reply to a message

POST /inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply

The message is sent from the inbox address with In-Reply-To and References set. The response is { "object": "inbox_email", "id", "email_id", "thread_id" }, where email_id is the sent email in /emails.

#Forward a message

POST /inboxes/{id}/threads/{thread_id}/emails/{email_id}/forward

Takes to (required), cc, bcc, subject, and an optional text or html note. The original message and its attachments are added below the note.

#Drafts

• POST /inboxes/{id}/drafts with any of to, cc, bcc, subject, html, text, reply_all, and reply_to_email_id or forward_email_id (a message ID of the inbox) to make it a reply or forward.
• GET /inboxes/{id}/drafts
• GET, PATCH and DELETE /inboxes/{id}/drafts/{draft_id}
• POST /inboxes/{id}/drafts/{draft_id}/send sends the draft and deletes it. If sending fails, for example because there is no recipient, the draft stays.

{
  "object": "draft",
  "id": "c2d1e0f9-0000-4000-8000-000000000002",
  "inbox_id": "5c0d1d9e-6a3b-4f55-8d7a-0e2d4a0b7f10",
  "kind": "reply",
  "thread_id": "f0a1b2c3-1111-4222-8333-444455556666",
  "reply_to_email_id": "9d8c7b6a-1111-4222-8333-444455556666",
  "forward_email_id": null,
  "reply_all": false,
  "to": [],
  "cc": [],
  "bcc": [],
  "subject": "",
  "html": "",
  "text": "Thanks, on it.",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z"
}

#Webhook events

Inbox events are listed under Event types.