Postmaster
(2026)
- Mac app · Email
- Swift
- AppKit
- IMAP and JMAP
A native Mac mail client for Gmail, Outlook and all IMAP or JMAP accounts. Each action shows immediately and goes to the server later. After a crash, a message goes out one time only. The HTML of a message cannot run code, and it loads nothing without approval.
The problem
A good mail client feels instant: a message leaves the inbox when you push a key. But the server confirms the change later, through IMAP, JMAP or the Gmail API. Between these two events, the app can quit, the network can stop, the server can refuse the change, and a refresh can bring the old state.
Sending has a stricter rule: each message must go out one time. Not zero times if the app crashes, and not two times when it starts again. Also, each new message is HTML from a stranger. The app must show it as its sender made it. But the HTML must not run code or tell the sender that you opened it.
My role
I made Postmaster: the product idea, the interface design, the native macOS app in Swift and AppKit, and the website.
The app uses its own clients for IMAP, SMTP, JMAP and the Gmail API. It has no server and no helper process. One Swift actor in the app controls the connections, the local store and the background work. Its only package dependency is Sparkle, for updates.
One message in the outbox
With Undo Send or Send Later, a message goes into the outbox in the local profile, and a timer sends it. Before each step, the app writes the full profile in one operation (atomically). The message gets its Message-ID when it goes into the queue. It keeps this ID for each attempt.
A. Queued
The message and its send time are in the profile. A timer waits for the send time.
B. Sending
The app writes the status “sending” in the profile before the provider call starts.
C. Checking
At launch, a message has the status “sending”: the app stopped during the send. The app looks for the Message-ID in the Sent folder.
D. Failed
The send failed. The outbox shows the error and the time of the next try.
E. Sent
The message leaves the outbox, and the app deletes its draft.
F. Withdrawn
Undo, Cancel or Edit removed the message. Edit opens it in a composer again.
One action on a message
The app keeps two layers of message state: the state that the server confirmed, and a projection with the pending changes on top. The list shows the projection. Jobs go to the server in lanes, with one lane for each conversation.
A. Shown
The change is in the projection, so the list shows it immediately. The confirmed state stays below it.
B. Waiting
The job waits for its conversation lane. A maximum of 4 jobs run at a time, and undo jobs go first.
C. Applying
The provider call runs. Before a change to more than one message, the app records an intent in the profile.
D. Confirmed
The change becomes part of the confirmed state and leaves the projection.
E. Dropped
The server refused the change. The change leaves the projection, the confirmed state shows again and the rows return.
The app stops during a send
The app crashes or quits after the server accepted the message, but before the outbox recorded it. A retry without a check sends a second copy.
The message gets its Message-ID when it goes into the queue. It keeps this ID for each attempt.
The outbox writes the status “sending” in the profile before the provider call. The app writes the profile atomically, so the profile is never half written.
At launch, the app sets a timer again for each message in the outbox. If a message still has the status “sending”, the app marks it as interrupted.
Before the app sends an interrupted message again, it looks for the Message-ID in the Sent folder, through IMAP, JMAP or the Gmail API. If the message is there, it leaves the outbox, and the app does not send it again.
A send fails
The network is down, the server refuses the message, or the token expired. The person thinks that the message went out.
A failed message stays in the outbox with the text “Delivery failed. Postmaster will retry automatically.” and the time of the next attempt.
The next attempt is after 2 minutes, then 4, then 8 and so on, to a maximum of 60 minutes.
The person can give a failed message a new send time, cancel it or edit it. A message that the app sends at that moment cannot change.
The outbox holds a maximum of 1,000 messages, each of a maximum of 32 MiB. It cannot grow without a limit.
A refresh brings back the old state
You archive a message. Then a sync that started one second before arrives, with the message still in the inbox. Without a guard, the message returns.
In the interface, a server snapshot does not replace a message with a pending change. The change stays on top of the confirmed state until the server answers.
In the engine, each local change gets a number from a clock. A sync that started before the change does not overwrite the flags of that message. It also does not remove the message from the cache.
Before the first server call of a batch change, the app records an intent in the profile. Until the app clears the intent, sync protects all messages in it. After a crash, Recover Messages shows the intent, and the person can apply it again.
The server refuses an action, or an undo arrives late
You archive 4 messages, and the archive fails for one of them. Or you undo an archive after you also starred the message, and the undo removes the star.
A refused change leaves the projection, so the confirmed state shows again without a manual rollback. The rows return to the list, and the selection returns too.
The error tells how much was done, for example “Archive: 3 completed; 1 failed.”
An undo is a new change. It restores only the fields that still have the value from the first change. A later change stays.
If an undo fails, the failed part stays on the undo stack.
Over IMAP, you can undo a move only if the server returned the new UID of the message. Without this UID, the app does not offer an undo, because the undo could move the wrong message.
New mail is late, or a folder changes on the server
A push connection stops without an error, a laptop wakes from sleep, or the server rebuilds a folder and gives its messages new UIDs.
For each account, one connection waits in IMAP IDLE on the inbox, or on the JMAP push stream. The app sends the IDLE command again every 285 s, before routers close a quiet connection.
When the connection stops, the app opens it again after 1 s. Each wait is two times longer, to a maximum of 300 s, with a random factor. If a connection was open for more than 60 s, the wait starts at 1 s again.
Push events that arrive close together cause one refresh, 300 ms after the first event.
A sync loop also runs every 60 s while the app is in front or notifications are on. At other times, it runs every 300 s.
If the server has QRESYNC or CONDSTORE, IMAP sync uses them. It then gets only the changed flags and the removed messages. If nothing changed, it stops after SELECT.
When UIDVALIDITY changes, the old UIDs are not valid. The app clears its cache for that folder and loads the folder again.
A message tries to run code or to track you
A stranger writes the HTML of a message. It can contain scripts, forms and remote images. A remote image can tell the sender when and where you opened the message, or it can point to a server on the local network.
The reader turns off JavaScript and sets a content security policy with default-src none. It cancels all navigation and uses a data store that it does not keep. The styles of the sender stay, so a message looks as its sender made it.
The reader removes scripts, frames and embedded objects. It removes form tags but keeps their content, and the policy refuses all form actions. The app never gets fonts or style sheets from the network.
The app blocks remote images until the person approves them. Then the app gets the images itself, not the web view, and gives them to the page as data.
An approved image must use HTTPS and go to a public address. The app checks the DNS answer and each redirect. It refuses localhost and private address ranges.
One image can be a maximum of 8 MiB, and all images of a message a maximum of 20 MiB. An image shows only after ImageIO decodes it. The bytes of the image, not its content type, prove that it is an image.
Numbers
30 s — longest Undo Send
undoDelay in send, in apps/macos/Sources/PostmasterNative/SwiftMailEngine+Compose.swift.
2 → 60 min — between attempts to send a failed message
retryDelay in deliverScheduled, in apps/macos/Sources/PostmasterNative/SwiftMailEngine+Compose.swift.
285 s — between renewals of IMAP IDLE
renewAfter in SimpleIMAP.watch, in apps/macos/Sources/PostmasterNative/SimpleMailProtocols.swift.
8 · 20 MiB — for one remote image, and for all images of a message
readerImage and resolvedImages in apps/macos/Sources/PostmasterNative/SwiftMailEngine+Reading.swift.
More work
Postmaster is a private repository. Paths are at commit 22e0c83.