The account's inbox

Every account Sente holds is backed by an identity, and every identity owns a real mailbox on sente.run. It receives what the third-party app sends — verification codes, security notices, invoices, replies from humans — and it can send as that address. This page covers the mailbox itself; for “block until the code arrives”, see Receive verification codes.

The address

An identity’s address is <local-part>@sente.run, and mail is live from the moment the identity exists.

Auto-provisioned (you called connect/register without an identityId): the local part is derived from the app’s hostname — https://github.com/login → github@sente.run, with a short random suffix if that address is taken (github-x7k2@sente.run).
Chosen: POST /v1/identities with localPart. A taken address returns 409 unless you pass onConflict: "suffix".

Role addresses (support, admin, security, abuse, postmaster, and the rest of the RFC-2142 set) are reserved for Sente’s own mail and can’t be allocated — 409 LOCAL_PART_RESERVED. Only the exact word is reserved: support-bot is fine. Mail to an address with no matching identity, or to an identity you’ve deleted, is dropped.

List messages

Newest first, archived hidden, 50 by default.

sente inbox --identity github@sente.run --limit 20
sente inbox --identity github@sente.run --direction inbound --since 2026-08-01T00:00:00Z

const msgs = await sente.messages.list(identityId, {
  direction: "inbound",
  kind: "otp",              // "otp" | "magic_link" | "other"
  since: "2026-08-01T00:00:00Z",
  limit: 20,
});

for (const m of msgs) {
  console.log(m.createdAt, m.fromAddr, m.subject, m.annotation?.kind);
}

msgs = sente.messages.list(
    identity_id,
    direction="inbound",
    kind="otp",              # "otp" | "magic_link" | "other"
    since="2026-08-01T00:00:00Z",
    limit=20,
)

for m in msgs:
    print(m.created_at, m.from_addr, m.subject, m.annotation.kind if m.annotation else None)

Filter	Values	Notes
`identityId`	an identity id	Omit it and the listing is org-wide — every identity you own, merged.
`direction`	`inbound` \| `outbound`	Outbound rows are the mail this identity sent.
`kind`	`otp` \| `magic_link` \| `other`	Matches the LLM annotation on inbound mail.
`since`	ISO timestamp	Strictly after.
`limit`	1–200	Default 50.
`includeArchived`	the literal `"true"`	Anything else is treated as false.

The org-wide feed is REST-only: both SDKs and the CLI take an identity as a required argument. For a dashboard or an audit sweep, call GET /v1/messages directly and group by the identityId each message carries.

curl "https://api.sente.run/v1/messages?kind=otp&limit=100" \
  -H "Authorization: Bearer $SENTE_API_TOKEN"

Read one message

A list row is already the full object, but you’ll usually fetch by id after a message.received webhook — that payload carries only the envelope, never the body.

# --json is a global flag: it goes BEFORE the subcommand
sente --json inbox --identity github@sente.run --limit 1

const msg = await sente.messages.get("msg_5b0e8d7c6f5a4e3d2c1b0a9f8e7d6c5b");
const { text, html } = msg.parsed as { text?: string; html?: string };

msg = sente.messages.get("msg_5b0e8d7c6f5a4e3d2c1b0a9f8e7d6c5b")
text = (msg.parsed or {}).get("text")
html = (msg.parsed or {}).get("html")

Bodies live under parsed: text and html for inbound mail, plus messageId (the sender’s own Message-ID header, used for threading). Outbound rows carry { text, html, inReplyTo }.

Attachments are not exposed. Only the text and HTML parts are parsed out; there is no attachment download endpoint. And email bodies are untrusted input — never hand a raw body to an agent that holds tools or credentials.

Send

text, html, or both — at least one is required. One recipient per call; there is no cc, bcc, or attachment support.

sente send \
  --identity github@sente.run \
  --to person@example.com \
  --subject "Build 4821 finished" \
  --text "All green. Report: https://…"

const sent = await sente.messages.send(identityId, {
  to: "person@example.com",
  subject: "Build 4821 finished",
  text: "All green. Report: https://…",
});
console.log(sent.deliveryStatus); // "sent"

sent = sente.messages.send(
    identity_id,
    to="person@example.com",
    subject="Build 4821 finished",
    text="All green. Report: https://…",
)
print(sent.delivery_status)  # "sent"

Mail leaves as the identity’s own address, DKIM-signed on sente.run, and is persisted as an outbound message.

Reply in-thread

Pass the Sente message id of the inbound message you’re answering. Sente looks up that email’s original Message-ID and sets In-Reply-To and References, so the reply threads properly in the recipient’s client.

sente send \
  --identity github@sente.run \
  --to person@example.com \
  --subject "Re: your question" \
  --text "Confirmed — rerunning now." \
  --reply-to msg_5b0e8d7c6f5a4e3d2c1b0a9f8e7d6c5b

await sente.messages.send(identityId, {
  to: inbound.fromAddr,
  subject: `Re: ${inbound.subject}`,
  text: "Confirmed — rerunning now.",
  inReplyTo: inbound.id,
});

sente.messages.send(
    identity_id,
    to=inbound.from_addr,
    subject=f"Re: {inbound.subject}",
    text="Confirmed — rerunning now.",
    in_reply_to=inbound.id,
)

The inReplyTo id must belong to the same identity. If it doesn’t — or the original email carried no Message-ID — the mail still sends, just unthreaded. The recipient address is not derived from it either: set to yourself.

Delivery status

Outbound messages start at sent and are updated from the provider’s delivery events. Poll the message by id, or list with direction=outbound.

`deliveryStatus`	Meaning
`sent`	Accepted by the sending provider.
`delivered`	Accepted by the recipient’s server.
`bounced`	Rejected. Repeated bounces to the same address hurt the shared domain — stop retrying.
`complained`	Marked as spam by the recipient. Stop mailing that address.
`rejected`	The provider refused to send it.

Inbound messages have deliveryStatus: null.

React to new mail

You want	Use
One specific verification email	`waitForOtp` / `waitForMagicLink`
Every inbound email, pushed to your service	Webhooks — `message.received`
Every inbound email, no public URL	`sente listen --identity <ref>` (add `--exec` to run a command per message, or `--forward <url>` to replay the real webhook shape at localhost), or the SDKs’ `messages.stream(identityId)`

Failure paths

Status	Body	What it means	What to do
`400`	a list of validation issues	No `text` and no `html`; empty or >998-char subject; malformed `to`; `limit` outside 1–200.	Fix the field named in the issue list.
`404`	`{"error": "identity not found"}`	The `identityId` isn’t in your org.	Check `GET /v1/identities`. Only sent when you pass one — the org-wide listing can’t 404.
`404`	`{"error": "not found"}`	That message id isn’t your org’s.	Check the id.
`429`	`{"code": "SEND_LIMIT_EXCEEDED", "limit": 100}`	The rolling 24-hour send brake.	Wait for the window to roll. See Limits.
`402`	`{"code": "PLAN_EMAIL_LIMIT_EXCEEDED", "limit": 150, "planId": "free"}`	Your plan’s monthly email cap. `402` because waiting won’t clear it inside the billing window.	Upgrade, or email support@sente.run.

Every identity sends from the same shared domain. Deliverability is a shared resource: one tenant sending unsolicited bulk mail gets the domain flagged, and a flagged domain means verification emails stop landing for everyone. Sending is for the account’s own correspondence — see the Acceptable use policy.

Next steps

Verification codes

Wait for an OTP or magic link and get just the value.

Webhooks

Push message.received to your service instead of polling.

Messages API

Every parameter, response, and error shape.

Get started

Accounts

Runs

Email

Events & audit

Trust

The account's inbox

The address

List messages

Read one message

Send

Reply in-thread

Delivery status

Archive

React to new mail

Failure paths

Next steps

Verification codes

Webhooks

Messages API

​The address

​List messages

​Read one message

​Send

​Reply in-thread

​Delivery status

​Archive

​React to new mail

​Failure paths

​Next steps

Verification codes

Webhooks

Messages API

The address

List messages

Read one message

Send

Reply in-thread

Delivery status

Archive

React to new mail

Failure paths

Next steps