diff --git a/wiki/Booking-Mail-Import.md b/wiki/Booking-Mail-Import.md index b6f26e8c8..281422ee1 100644 --- a/wiki/Booking-Mail-Import.md +++ b/wiki/Booking-Mail-Import.md @@ -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 `\n\n`, 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 diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 86401651a..3819852c4 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -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. | | --- diff --git a/wiki/MCP-Tools-and-Resources.md b/wiki/MCP-Tools-and-Resources.md index e58943c45..3a7c00885 100644 --- a/wiki/MCP-Tools-and-Resources.md +++ b/wiki/MCP-Tools-and-Resources.md @@ -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. |