docs(wiki): the mail import's deferred folder, recipients, limits and sender hint

Describes TREK/deferred, which header names the address, the webhook's 401
and 429 answers and where the sender hint can show at all. The variables
table leaves an empty default blank instead of a dash.
This commit is contained in:
Maurice
2026-11-13 17:05:59 +01:00
parent 264f352502
commit f7bad3c5b3
3 changed files with 25 additions and 8 deletions
+19 -2
View File
@@ -26,7 +26,13 @@ mail at once. Treat the address like a password: whoever knows it can put bookin
TREK reads one mailbox every two minutes. Point a catch-all, or a mailbox with sub-addressing (`trek+anything@`), at
it and use the matching address template. Read mails move to the folder `TREK/processed` and are never deleted, so
anyone with access to the mailbox can read them.
anyone with access to the mailbox can read them. A mail TREK cannot take for now, because its address took its 50 mails
of the day or its person has 200 bookings waiting, moves to `TREK/deferred` and is offered again on every run for three
days; after that it moves to `TREK/processed` as well.
TREK files a mail under the address in the topmost `Delivered-To` header, else the topmost `X-Original-To`, which the
receiving server adds; only without either does it read `To`. A mail addressed to several people's addresses reaches
each of them.
| Field | Default |
|---|---|
@@ -49,7 +55,7 @@ Each request carries three headers:
| Header | Value |
|---|---|
| `X-Trek-Timestamp` | The time of sending, in Unix seconds. Requests more than five minutes off are refused. |
| `X-Trek-Recipient` | The address the mail was sent to (the envelope recipient). Optional; without it TREK reads `Delivered-To`, `X-Original-To` and `To`. |
| `X-Trek-Recipient` | The address the mail was sent to (the envelope recipient). Optional; without it TREK reads the topmost `Delivered-To`, else `X-Original-To`, else `To`. |
| `X-Trek-Signature` | `sha256=` followed by the hex HMAC-SHA256 of `<timestamp>\n<recipient>\n<raw mail>`, keyed with the secret. |
A Cloudflare Email Worker that forwards a mail:
@@ -85,6 +91,17 @@ export default {
Postmark and Mailgun forward inbound mail as JSON, not raw; put a small function like the one above between them and
TREK. The answer is `{"accepted":true,"duplicate":false}`; a mail sent twice is stored once.
A request whose headers cannot carry a valid signature is refused with `401` before its body is read. One address may
post 120 requests a minute, and TREK reads four mails at once; above either it answers `429`, as it does when an
address took its mails of the day or its person's open bookings are full, so the sender tries again later.
## The sender hint
An entry shows whether its sender is confirmed: the mail came from the person's own account address, and the
receiving mail server found a DKIM signature of that address's domain or a DMARC pass for it. Only the IMAP transport
can show this, since only there the receiving server's `Authentication-Results` header is the topmost one; a mail that
came by webhook or upload is always shown as not confirmed. The hint never stops a booking.
## Status
The **Status** card in the dialog shows the last successful read, the last error, and the mails of the last day by
+5 -5
View File
@@ -244,14 +244,14 @@ in the admin dialog; unset, the dialog decides.
| Variable | Description | Default |
|--------------------------------|-------------------------------------------------------------------------------------------------------------|---------|
| `MAIL_INGEST_TRANSPORT` | `off` (uploads only), `imap` or `webhook`. | `off` |
| `MAIL_INGEST_IMAP_HOST` | The mailbox TREK reads every two minutes. A host on your own network needs `ALLOW_INTERNAL_NETWORK=true`. | — |
| `MAIL_INGEST_IMAP_HOST` | The mailbox TREK reads every two minutes. A host on your own network needs `ALLOW_INTERNAL_NETWORK=true`. | |
| `MAIL_INGEST_IMAP_PORT` | `993` for TLS, `143` for STARTTLS. | `993` |
| `MAIL_INGEST_IMAP_TLS` | `tls` (encrypted from the first byte) or `starttls`. | `tls` |
| `MAIL_INGEST_IMAP_USER` | IMAP login. | — |
| `MAIL_INGEST_IMAP_PASS` | IMAP password. | — |
| `MAIL_INGEST_IMAP_USER` | IMAP login. | |
| `MAIL_INGEST_IMAP_PASS` | IMAP password. | |
| `MAIL_INGEST_IMAP_MAILBOX` | The folder the mails arrive in. Read mails move on to `TREK/processed`; nothing is deleted. | `INBOX` |
| `MAIL_INGEST_ADDRESS_TEMPLATE` | The forwarding address, each person's token where `{token}` stands, e.g. `trek+{token}@example.com`. | — |
| `MAIL_INGEST_WEBHOOK_SECRET` | The key the webhook sender signs each mail with (HMAC-SHA256), at least 32 characters. | — |
| `MAIL_INGEST_ADDRESS_TEMPLATE` | The forwarding address, each person's token where `{token}` stands, e.g. `trek+{token}@example.com`. | |
| `MAIL_INGEST_WEBHOOK_SECRET` | The key the webhook sender signs each mail with (HMAC-SHA256), at least 32 characters. | |
---
+1 -1
View File
@@ -282,7 +282,7 @@ tool reads or makes a forwarding address, since an address carries its secret to
|---|---|
| `list_mail_inbox` | The entries waiting for a decision, each with why it waits, the booking as read, the trip it suggests and the mail's subject; `status: "resolved"` lists the decided ones. |
| `add_mail_booking` | Add a waiting booking to the trip it suggests, or to another (`trip_id`). Undoable for seven days. |
| `move_mail_booking` | Move a booking added from a mail into another trip while it can still be undone. |
| `move_mail_booking` | Move a booking added from a mail into another trip while it can still be undone. Only the person who forwarded the mail can move it. |
| `file_mail_booking` | Put the mail into a trip as documents, without a booking. Needs the Documents addon. |
| `discard_mail_booking` | Set a waiting entry aside. |
| `undo_mail_booking` | Remove a booking added from a mail with its stay, cost and documents, within seven days. |