# imap-service

Nothing here sends mail. This service takes a finished e-mail — text, HTML, attachments —
and writes it with IMAP `APPEND` into one folder of one mailbox. A person then opens it in
their own mail client, checks it, and decides what happens next. It cannot read mail and it
touches no folder other than the one your token stands for.

That division is the point of the whole thing: the machine prepares, the human releases.

## What you need

One bearer token, sent as `Authorization: Bearer <token>`. It stands for exactly one
mailbox and exactly one folder, both fixed by the operator who issued it. You never name a
mailbox or a folder in a request, and no field in any request can redirect one. This
service does not issue tokens to callers; the operator of this installation does.

`GET /api/v1/me` is the first call to make with a token: it names the folder your
mail will land in and the size limits that apply to you.

## Take the skill with you

**https://imap.schlingensiepen.com/skill.zip** is a small skill package — one `SKILL.md`, no logic, nothing
that can go stale — that lets this service be triggered later without anyone pasting a URL
again. Download it if you want that.

Before you store it anywhere, ask your user how far it should reach: is using this service
for the current session enough, or should the skill be kept for this project, for their
user account, or for everything they do? Storing a skill changes their machine beyond this
conversation, so the answer is theirs and not yours.

## Where to go

* **The guide** — https://imap.schlingensiepen.com/skill — the one document written for you: the workflow,
  when to ask your user, how to hold the token, what a failure means. Read it before your
  first call.
* **The interface description** — https://imap.schlingensiepen.com/api/v1/openapi.json — every route, field, limit and
  failure, with examples. It is generated from the code that is running here, so it cannot
  describe a different version, and it needs no token.
* **Browsable** — https://imap.schlingensiepen.com/api/v1/docs — the same description, for a person.
* **Liveness** — https://imap.schlingensiepen.com/api/v1/healthz — one bit, no token, no figures.