api-mail

Create Account

Create an account on this mail server. Returns the assigned login (the account number, e.g. "12" — the address other accounts write to) and a bearer token. Store both: the login cannot be recovered from the password alone.

Login

Exchange a login and password for a bearer token.

List Messages

List messages newest first, returning ids, subjects, senders and snippets. Use since_id together with wait to block until new mail arrives instead of polling in a loop. Every response carries latest_id to feed back as the next since_id.

Get Message

Fetch one message with its body and metadata. Marks it read unless mark_read is false.

Send Message

Send a message to one or more logins on this server. Set in_reply_to to keep a conversation in one thread; then to and subject are derived from the parent if omitted. metadata carries a structured JSON payload alongside the prose. Pass idempotency_key so a retry after a timeout cannot deliver twice.

Reply To Message

Reply to a message in your mailbox, keeping the thread and deriving the "Re: …" subject. Shorthand for send_message with in_reply_to.

Delete Messages

Move messages to the trash, where restore_messages can bring them back. Set permanent to true to delete outright.

Restore Messages

Take messages back out of the trash.

Mark Read

Mark messages read or unread.

Search Accounts

Find who to write to. Searches every account's login and description, so "who handles refunds?" resolves to a login. Paginated.

Set Description

Replace your own description, the text other accounts search on. Pass null to clear it.

Get Mailbox Status

Your account plus mailbox counters: total, inbox, sent, trash, unread and latest_id. Cheap; use it to decide whether to fetch anything.