Mail

Calling it

This is your own data, so a call has to say who you are. Make a token at /token and send it as a header.

curl -H "Authorization: Bearer $MU_TOKEN" \
  https://micro.mu/api/v1/mail/inbox

The same method over MCP, which is what an agent speaks: mail_inbox. The answer is identical.

How every call behaves →

Methods

GET /api/v1/mail/inbox

List the account's most recent messages — read my mail, check my inbox

Needs an account.

Argument	Type	Description
`tag`	string	Only messages sent to this plus-address tag
`offset`	number	Matching messages to skip
`limit`	number	Max messages (default 10)

curl \
  -H "Authorization: Bearer $MU_TOKEN" \
  "https://micro.mu/api/v1/mail/inbox"

tagoffsetlimit

GET /api/v1/mail/info

How to reach the caller here: the handle, the email address if this instance has a mail domain, and whether mail from outside can arrive at all. Pass a tag for a separate one (you+tag) — give that out, then read only its messages with mail_inbox(tag)

Needs an account.

Argument	Type	Description
`tag`	string	A label for this handle, e.g. "research" or "receipts". Omit for the plain one

curl \
  -H "Authorization: Bearer $MU_TOKEN" \
  "https://micro.mu/api/v1/mail/info"

tag

POST /api/v1/mail/markread

Mark specified inbox message IDs, or explicitly all current inbox messages, as read. Changes read status only; does not read, summarize or triage the content.

Needs an account. Changes something, so POST only.

Argument	Type	Description
`ids`	array	Message IDs to mark read; use all instead to clear the inbox unread count
`all`	boolean	Explicitly mark all current inbox mail as read

curl -X POST \
  -H "Authorization: Bearer $MU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://micro.mu/api/v1/mail/markread

idsall

GET /api/v1/mail/read

Read your correspondence by id in bounded body-character pages, including attachment names. Follow the returned next offset for the rest. Omitting id retains the legacy inbox summary

Needs an account.

Argument	Type	Description
`offset`	number	Body character offset
`limit`	number	Body characters per page; default and maximum 2000
`id`	string	Message id from mail_inbox or mail_search

curl \
  -H "Authorization: Bearer $MU_TOKEN" \
  "https://micro.mu/api/v1/mail/read"

offsetlimitid

POST /api/v1/mail/search

Search the account's mail and return matching messages

Private search terms belong in a POST body. Needs an account.

Argument	Type	Description
`tag`	string	Only messages sent to this plus-address tag
`offset`	number	Matching messages to skip
`query`	string	What to look for
`limit`	number	Max results (default 10)

curl -X POST \
  -H "Authorization: Bearer $MU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://micro.mu/api/v1/mail/search

tagoffsetquerylimit

POST /api/v1/mail/send

Write to somebody, as you. A username reaches them on this instance and is free; a full email address leaves over SMTP under this instance's domain, so a reply comes back to your inbox, and is charged. Resolve a name with contacts_find first. Mail that leaves needs MAIL_DOMAIN configured on the instance

Needs an account. Changes something, so POST only. Withheld from the agent — a person or a program only.

Argument	Type	Description
`to` *	string	Recipient: a username on this instance, or a full email address. Resolve a name with contacts_find first
`subject` *	string	Message subject
`body` *	string	Message body, plain text

curl -X POST \
  -H "Authorization: Bearer $MU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"body","subject":"subject","to":"to"}' \
  https://micro.mu/api/v1/mail/send

to *subject *body *

The same methods are tools over MCP, and every service on this instance is in one reference.