mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 11:36:05 +00:00
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:
@@ -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
|
||||
|
||||
@@ -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. | |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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. |
|
||||
|
||||
Reference in New Issue
Block a user