Fluid Recall Mailboxes API
The Mailboxes API from Fluid Recall — 2 operation(s) for mailboxes.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fluidrecall-com:fluidrecall-com-mailboxes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fluid Recall Mailboxes API
version: 0.0.0
description: 'System of record for spaced recall. One service with four doors: MCP at POST /mcp (also /api/mcp), Markdown /api/v1/agent and /api/v1/dev, and JSON /api/v1. Agents may use whatever works best. None is deprecated. JSON operations sit at the /api/v1 root (/due, /decks, /reviews). Request bodies are JSON. Markdown responses use Content-Type text/plain; the body is Markdown. MCP is stateless Streamable HTTP. Send Authorization: Bearer . No Mcp-Session-Id. The same MCP door speaks the ChatGPT MCP Events subset (events/list, events/subscribe, events/unsubscribe) with webhook-only delivery. Muse bootstraps a personal API token with POST /accounts or POST /bootstrap and keeps drilling. The bearer token is the tenant. This API decides what is due and when it is due next. Bootstrap, reviews, and unauthenticated reads are rate limited. HTTP 429 is retryable. ---'
servers:
- url: /api/v1
security:
- bearerAuth: []
- poppyDpop: []
tags:
- name: Mailboxes
paths:
/mailboxes:
get:
operationId: listMailboxes
summary: List owned fluidrecall.com mailboxes
description: Read. Returns mailboxes this bearer owns. Unclaimed inbound addresses are omitted until ensureMailbox. Heidi is heidi@fluidrecall.com. Claim it with POST /mailboxes. Another token cannot see these rows.
x-muse-action-class: read
responses:
'200':
description: Owned mailboxes.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- mailboxes
properties:
mailboxes:
type: array
items:
type: object
'401':
description: Missing or wrong token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Mailboxes
post:
operationId: ensureMailbox
summary: Create or claim a fluidrecall.com mailbox
description: 'Write. address is a local-part or local@fluidrecall.com. Creates the mailbox for this token, or claims an unowned inbound row. Another account''s address is 409. Seed Heidi with { "address": "heidi@fluidrecall.com", "displayName": "Heidi" }.'
x-muse-action-class: write
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- address
properties:
address:
type: string
minLength: 1
maxLength: 254
displayName:
type:
- string
- 'null'
maxLength: 80
responses:
'200':
description: Mailbox plus created/claimed flags.
content:
application/json:
schema:
type: object
'400':
description: Invalid address.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or wrong token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Address owned by another account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Mailboxes
/mailboxes/{mailboxId}/messages:
get:
operationId: listMailMessages
summary: List message headers in one owned mailbox
description: 'Read. Headers only: from, to, subject, dates, thread. No bodies. Prefer this before getMailMessage. Do not download a whole mailbox unless the person asked. Another token''s mailbox is 404.'
x-muse-action-class: read
parameters:
- name: mailboxId
in: path
required: true
schema:
type: string
format: uuid
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 25
- name: cursor
in: query
required: false
schema:
type: string
responses:
'200':
description: Header page. bodyIncluded is false.
content:
application/json:
schema:
type: object
'401':
description: Missing or wrong token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No mailbox with that id for this token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Mailboxes
post:
operationId: sendMailMessage
summary: Send from an owned mailbox
description: Write. Ask before sending. From is the owned mailbox. Recipients may be arbitrary addresses when Email Sending allows it. Requires to, subject, and text and/or html. Optional inReplyTo and references set threading headers.
x-muse-action-class: write
parameters:
- name: mailboxId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- to
- subject
properties:
to:
oneOf:
- type: string
- type: array
items:
type: string
cc:
type: array
items:
type: string
subject:
type: string
minLength: 1
maxLength: 998
text:
type: string
maxLength: 64000
html:
type: string
maxLength: 128000
inReplyTo:
type: string
references:
type: string
responses:
'201':
description: Stored outbound message, including bodies.
content:
application/json:
schema:
type: object
'400':
description: Invalid body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or wrong token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No mailbox with that id for this token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: EMAIL send_email binding is not available.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Mailboxes
components:
schemas:
Error:
type: object
additionalProperties: false
required:
- code
- message
- retryable
properties:
code:
type: string
enum:
- BAD_REQUEST
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- CONFLICT
- UNAVAILABLE
- RATE_LIMITED
message:
type: string
retryable:
type: boolean
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Personal Fluid Recall API token from POST /accounts (or POST /bootstrap). Save it for API calls. The operator break-glass secret is a different credential and cannot call drill operations.
poppyDpop:
type: http
scheme: DPoP
description: 'Personal Agent Protocol (Poppy v0.1) Session Token from POST https://fluidrecall.com/oauth/token, sent as Authorization: DPoP <token> with a DPoP proof header on every call. poppy:read allows reads and poppy:write allows changes; personal API token management is not available. See https://fluidrecall.com/.well-known/poppy.json and https://fluidrecall.com/docs/personal-agent-protocol.'