Local features
How snooze, send later, reminders, rules, undo send and unsubscribe run inside the engine on your computer, with no Airpost server.
Many mail clients that offer snooze or send later run them on the vendor’s servers, which then need access to your mailbox. Airpost runs them in the engine on your computer (or on a server you run yourself). Nothing is sent to an Airpost service, and no window has to be open: the engine acts on its own schedule.
The catch is the same one any local program has: the engine has to be running at the time. Closing the window keeps it running; quitting the app stops it unless Keep Airpost running in the background is on. See Background mode.
For how to use these features, see Send later, snooze and reminders, Mail rules and Unsubscribe.
Metadata and the expiration executor
Snooze, send later and reminders are stored the same way: as plugin metadata on a thread or a draft, with an expiration time. The plugin ids are thread-snooze, send-later and send-reminders. The metadata lives in the ModelPluginMetadata table of airpost.db.
Each account’s metadataExpiration thread sleeps until the next expiration. Saving metadata with an earlier time wakes it at once. When something comes due, the expiration executor acts on it inside the engine. The engine announces this in hello as the expiration-executor feature, and clients that see it leave those rows alone, so two open clients can’t fire the same send twice.
Metadata changes go through the same task (SyncbackMetadataTask) a client would use, so if you later connect an Airpost server, they reach it the same way.
Snooze
Snoozing a thread does two things: it moves the thread to your Snoozed folder (Airpost/Snoozed on new accounts; the Mailspring/Snoozed folder from Mailspring is recognised too) and writes thread-snooze metadata with the wake time. Because it’s a real folder move on the server, the thread is also out of your inbox in webmail and on your phone.
When the time comes, if the thread is still in Snoozed, the engine moves it back to the inbox. With Move snoozed mail to the top of the inbox when it comes back on, it also resurfaces the thread: it sends a short hidden message from your account to itself, as a reply in that thread, so the thread rises to the top of the inbox in every mail client, not only Airpost. The text of that message is the resurfacing.snoozeBody setting.
If you moved the thread out of Snoozed yourself in the meantime, the engine only clears the metadata.
Send later
A scheduled send is a draft with send-later metadata. When it comes due, the engine clears the metadata, finalises the current version of the draft and queues a SendDraftTask, then applies the after-send action.
Some details that matter if you schedule from several places:
- Missing pieces. If the draft’s body or an attachment isn’t on this computer yet (it was scheduled on another device), the engine fetches it and looks again after 1, 2, 4 and 8 minutes. If it’s still missing, the send fails and the error is written on the metadata.
- Offline at the time. The send waits for the account to come back online, for up to a day. See Sync.
- Bodies from send hooks. When a client’s send hooks produced per-recipient bodies, they’re kept in
<profile>/pending-sends/<accountId>/<draftId>.jsonuntil the send goes out. They’re kept out of the metadata because metadata can sync to your other devices, and these are for this one send. - Left to the client. A send marked
clientFinalize(third-party send transforms from plugins) is handed to the client as ametadata-expirationdelta instead.
Undo send
Undo send is send later with a short delay. When you click Send, the draft gets send-later metadata a few seconds in the future, marked isUndoSend. The delay comes from Preferences > Composing & sending > Undo Send (the core.sending.undoSend setting): 5 seconds by default, or 15, 30 or 60, or off.
Send now instead moves the time earlier. Because the engine does the send, closing the window during the undo window doesn’t lose the message.
Reminders
A send reminder brings a thread you sent back to your attention if nobody replies by a time you pick. The engine checks on every save of the thread: when a reply from someone else arrives, the reminder is cleared. If the time comes with no reply, the engine marks it to notify, clears the expiration and resurfaces the thread the same way snooze does (text from resurfacing.reminderBody).
Mail rules
Rules are stored in the mailRules setting in the engine’s settings.json, and each account’s mailRules thread applies them to arriving mail.
- What counts as arriving. A message is checked once, when the engine has both its body and a copy you received. Drafts, mail you sent to others, and mail dated before you turned rules on (
mailRulesAutoSince) are skipped. - Order. Rules run one at a time over the batch, in the order you set, so a later rule can undo an earlier one. Each acts once per thread.
- Actions are ordinary tasks (mark read, star, trash, move, label, archive), run on the thread. A forward is built as a draft and sent without an undo window. Rule actions can’t be undone.
- Failures. A rule that fails, such as an invalid regular expression or a folder that’s gone, is disabled with the reason, and every client gets
rules.disabled. It shows as Stopped in Preferences. - Existing mail. Run now calls
rules.reprocess, which walks your inbox newest first, 50 threads at a time, and reportsrules.progress. It stops onrules.cancel, when the client disconnects, or when the account stops.
Mail that arrived while the engine wasn’t running isn’t checked later; Run now covers it.
Unsubscribe
messages.unsubscribe acts on the message’s List-Unsubscribe header:
| What the header offers | What the engine does |
|---|---|
| One-click (RFC 8058) | Makes the HTTPS POST itself. Nothing opens. |
mailto: | Sends the unsubscribe email from your account, as a normal SendDraftTask. |
| A web link only | Returns the link to the client, which opens it in your browser. |
The header is stored when the body is fetched. If you unsubscribe from a message whose body isn’t on this computer yet, the engine fetches it first. Links found only in the message body are left to the client to show. For agents, unsubscribe needs the send access level because it can send mail.
The undo log
Undo for mail actions is kept in the engine, not in the window, so it works the same from the app, the CLI and agents. Each undoable intent (archive, move, label, trash, star, read), snooze or delayed send adds an entry. The log holds up to 100 entries for up to 24 hours, in memory: it doesn’t survive an engine restart.
Clients use undo.list, undo.apply, undo.redo and the undo.changed notification. The undo is built from what the task’s local phase actually changed. For read, star and label changes that’s per message, so undo restores each message’s own previous value instead of flipping the whole thread.
With an Airpost server
None of this needs a server. If you connect one later, two things change:
- Before acting on a due item, the engine claims it on the server, keyed on a Message-ID all your devices share, so only one of your devices sends or unsnoozes. If the server doesn’t answer, this device acts anyway, which can mean a rare duplicate.
- A scheduled draft with open or link tracking on is sent tracked, when the server offers tracking.
Related
- The engine: the threads these run on.
- Profiles and data: where settings and pending sends are stored.