How to use Unpile

Unpile is laid out like Apple Mail: sidebar → message list → message. Everything here works on the Gmail account selected at the bottom of the sidebar.

Signing in

The first time you open the app, click Sign in with Google. Your browser opens; choose your account and approve both permissions. When the browser says "Signed in to Unpile", come back to the app.

• More accounts: use the account menu at the bottom of the sidebar → Add Account…, or Settings → Accounts.
• Switching accounts: pick one from the same menu. Each account keeps its own sign-in.
• Signing out: the account menu or Settings → Accounts → Sign Out. This also revokes the app's access at Google.

If Google shows "Access blocked", your account isn't in the beta yet: write to us and we'll add it.

Sidebar

• Mailboxes:

  • All Unread: every unread message, from any folder.
  • Inbox, Starred, Important, Sent.
  • All Mail.

  The number next to each is its unread count.

• Labels: your Gmail labels. Nested labels (Parent/Child) are indented.

  • + creates a label, optionally nested under another.
  • Right-click a label to Rename… it (labels nested under it follow) or Mark All as Read.

• Top Senders: everyone with unread mail, most unread first (see below).

• Filters: all Gmail filters on the account (see below).

Message list

• Unread only and Refresh (⌘R): the buttons at the top of the list. You rarely need Refresh: every minute, and whenever you switch back to Unpile, it checks Gmail for changes. New mail appears at the top, and mail read or labelled elsewhere (your phone, the web, Gmail filters) updates in place, along with the counts. Nothing you're looking at is reloaded.
• The bar above the list: All · By Sender · By Domain groups the list into one section per sender (or per domain), in order of their newest message, each with its unread count and a Review button. Click a section's header to fold it away or open it again (⌥-click: every section); the button next to the picker collapses or expands them all. Also in the View menu: ⌃⌘S, ⌃⌘D, ⌃⌘0, and ⌃⌘← / ⌃⌘→ to collapse/expand all. Your grouping is remembered.
• Search: the search field accepts full Gmail syntax (from:, subject:, has:attachment, older_than:1y, …). Press Return to search; clear the field to go back.
• Select several: ⌘-click or ⇧-click, or ⌘A for everything loaded. More messages load as you scroll.
• In All Unread, or with Unread Only on, mail you mark read leaves the list right away and the next message is selected, so the list shrinks as you go. Undo (⌘Z) puts it back where it was. (A Review keeps its rows until you close it, and mail marked read just by opening it stays while you read it.)
• E reads and archives the selected messages; Backspace or Delete moves them to Trash (see Delete). The next message is selected, so holding the key works down the list.
• Right-click a message for:
  • Mark as Read/Unread, Read & Archive, Move to Trash;
  • Add Label;
  • your Quick Actions;
  • Review, Mark All as Read, Organize, Junk or Delete Everything for that sender.

While a message's body loads, its header, labels and sender card are already shown from the list.

Opening a message does not mark it read, so looking never changes anything. To change that, use Settings → General → Mark messages as read when I open them.

The sender card

Every open message has a card under its header:

✦ 29 unread from jobalerts-noreply@linkedin.com ▾ [Mark 29 as Read] [Review…] [Organize…] [Unsubscribe…]

The ▾ menu switches between this exact address and anyone at the domain (e.g. all of linkedin.com). The count is exact: every matching unread message, in every folder. For common email providers like gmail.com or outlook.com, “anyone at the domain” would be everyone you know, so it isn't offered; turn on Settings → General → Allow “anyone at” common email providers to get it back, and Unpile asks before using it.

Mark N as Read (⇧⌘R)

Marks every unread message from that sender as read in one click. A toast at the bottom says how many were changed and offers Undo, which marks exactly those messages unread again.

Review… (⇧⌘L)

Switches the list to only that sender's unread mail, across all folders. A blue bar at the top shows which sender you're reviewing. Then:

1. Click, ⌘-click, or Select All (⌘A) to choose messages.
2. Click Mark as Read (⇧⌘U) in the right pane.

Messages you didn't select stay unread. Marked messages stay in the list, shown as read, until you refresh, so nothing jumps around. Click ✕ on the blue bar to leave review mode.

Organize… (⇧⌘O)

Files everything from the sender in one sheet:

• Which mail: only this address, or anyone at the domain.
• Put in label: an existing label, a new one (type the name; Parent/Child nests it), or none.
• Mark as read and/or Skip the Inbox (archive).
• Apply to:
  • Mail I already have: the count of matching messages is shown.
  • New mail from now on: creates a Gmail filter, so Gmail keeps doing this automatically.

Apply does it, and the toast offers Undo. Undo puts back exactly what changed:

• it re-adds unread only to messages that were unread;
• it re-adds Inbox only to messages that were in the Inbox;
• it removes the label only from messages that didn't already have it;
• it deletes the filter it created.

Save as Quick Action turns the current settings into a toolbar button (next section).

Unsubscribe… (⇧⌘N)

Shown when the sender's mail carries an unsubscribe link (most newsletters and marketing mail do; personal mail doesn't). Also in the right-click menu and the Message menu. It asks first, because an unsubscribe can't be undone, and offers Unsubscribe and Mark All as Read to clear what's already here at the same time.

How it unsubscribes depends on what the sender supports:

• One click (most bulk senders): Unpile tells the sender directly. No email is sent, no page opens, nothing is deleted.
• A web page: it opens in your browser to finish there.
• Email only: a ready-to-send message opens in your mail app. Unpile can't send mail, so you send it.

Senders may keep mailing for a few days after an unsubscribe. For mail that never asked your permission, use Junk instead: unsubscribing tells a spammer the address is real.

Top Senders

Top Senders (in the sidebar) ranks everyone you have unread mail from, most unread first, with a bar showing how each compares with the biggest. Domains ranks by domain instead (all of linkedin.com together); senders at common email providers like gmail.com always stay separate.

Pick a row for its sender card (Mark N as Read, Review…, Organize…, Delete…, Unsubscribe…) and its latest unread subjects. Right-click a row for the same actions. A row you clear leaves the list and the next one is selected. Closing a Review started here comes back to Top Senders.

The first time, Unpile reads the sender of every unread message in the background (it shows how far it has got). After that it only reads new mail, and with the offline cache on it remembers senders between launches, so the ranking appears right away.

Junk

For mail that's really junk, click the red Junk button in the toolbar (⇧⌘J). It's also in the right-click menu and in the Message menu. Everything from that exact address is moved to Spam and marked read, and the messages disappear from the list. The toast offers Undo, which puts back exactly what changed.

• It always matches the exact address, never the domain, so junking one gmail.com sender can't touch all of gmail.com.
• Junk in the sidebar shows what's in Spam, so you can check it or rescue messages.
• Gmail permanently deletes Spam after 30 days.
• No filter is created for future mail, because Gmail filters can't send mail to Spam. Gmail learns from what you mark as spam, so future mail from that sender usually lands there on its own.

Delete

Select messages and press Backspace or Delete (or right-click → Move to Trash). To clear out a whole sender, click the red Delete 37… button on the sender card (the number is every message from that sender, read or unread), or right-click → Delete Everything from…. It uses the sender card's scope (the exact address, or anyone at the domain) and asks first, saying how many messages and how many of them are unread. When unsubscribing, Unsubscribe and Move All to Trash does both in one step.

• Deleted mail goes to Gmail's Trash, exactly as Gmail's own Delete button does. Its labels and read state stay as they were.
• The toast offers Undo (or press ⌘Z), which brings everything back where it was. Deletes in quick succession share one toast and one Undo.
• Gmail permanently deletes Trash after 30 days. Until then you can still find it in Gmail's Trash.
• Unpile can't delete mail permanently: Gmail doesn't allow that with the permission Unpile asks for.

Doing several things at once

⌘Z undoes the last change to mail, even after its toast has gone; press it again to undo the one before, and so on. ⇧⌘Z redoes what you just undid. While you're typing in a text field, ⌘Z undoes the typing instead.

Buttons never lock while something is running. Click a quick action or Junk on one message, open the next and click again. Each running operation shows its own progress pill at the bottom of the window. When done, each turns into its own toast with its own Undo. Up to four toasts are kept for 10 seconds.

Quick Actions

Quick Actions are your own one-click toolbar buttons. Example: Updates for marketing mail you don't want in your inbox, but don't want in Spam either. With a message open, click Updates in the toolbar, and everything from that sender:

• gets the Updates label, in the color you chose;
• is marked read and/or archived, if you chose that;
• keeps getting filed that way, through a Gmail filter.

The toolbar shows one button per Quick Action, colored by its label color. They work on the open message's sender, or on the selected messages' sender if they all share one. They're also in the right-click menu, and the first nine have shortcuts ⌃1 … ⌃9. Every run can be undone from the toast.

Managing them: Settings (⌘,) → Quick Actions, or Edit Quick Actions… in the toolbar's ⋯ menu. Quick actions that don't fit in the toolbar are in that menu too, keeping their ⌃ shortcuts.

• Add Quick Action has these settings:
  • Label: type a name or pick an existing label. If the label doesn't exist yet, it's created the first time you use the button.
  • Color: one of Gmail's label colors. It's applied to the Gmail label too, so the label shows the same color in Gmail and in the sidebar.
  • Match: the sender's address, or their whole domain.
  • Mark as read, Skip the Inbox.
  • Apply to: mail you already have and/or new mail (a Gmail filter).
• Edit, delete (🗑), and drag to reorder. Order decides the toolbar order and the ⌃ numbers.

Quick Actions refer to labels by name, so the same buttons work on all your accounts. With iCloud sync on (Settings → General), they're the same on all your Macs.

Filters

Click Filters in the sidebar. Each filter is described in plain words, e.g. From paypal.com → Label "Finance", Mark read.

• Edit: select a filter and change its criteria (From, To, Subject, Has the words, Doesn't have, Has attachment) or its actions:

  • apply a label (+ creates a new one);
  • mark as read, skip the Inbox, star;
  • importance, category, never send to Spam.

  Then Save Changes (⌘S). Gmail can't edit filters in place, so saving creates the new version and then removes the old one. If that fails, the old one is put back.

• New filter: click + in the toolbar.

• Show Matching Mail: opens All Mail with the filter's equivalent Gmail search.

• Run on Existing Mail…: Gmail filters only affect new mail. This applies the filter's actions to mail you already have, after confirming how many messages match.

• Delete Filter: removes only the rule. No mail is changed.

Filters created in Gmail that delete or forward mail are shown with a warning and kept as they are when you edit them. The app never adds those actions itself, and "Run on Existing Mail" skips deleting.

Moving filters to another label (Settings → Filters)

Settings (⌘,) → Filters lists your filters grouped by the label they put mail in, e.g. Updates · 12 filters. To send them somewhere else, e.g. everything you filed as Updates should now go to Marketing:

1. Tick filters, or Select All in a group.
2. Move to: pick a label, or New Label….
3. Choose what else to change:
   • Also move the mail these filters already labelled: for each filter, messages carrying the old label move to the new one.
   • Also update quick action "Updates": shown when a quick action used the old label. It retargets that action, so its button files into Marketing from now on.
4. Click Move Filters. The toast offers Undo, which restores the filters, the mail and the quick actions.

Each filter's other actions (mark read, archive, star…) are kept. If the result would be identical to a filter you already have, the two are merged instead of duplicated.

Keyboard shortcuts

Shortcut	Action
⇧⌘U	Mark selected as read
⌥⇧⌘U	Mark selected as unread
⇧⌘R	Mark all from sender as read
⇧⌘L	Review unread from sender
⇧⌘O	Organize sender…
E	Read & archive selected (in the message list)
⌫ or ⌦	Move selected to Trash (in the message list)
⇧⌘J	Move everything from sender to Junk
⇧⌘N	Unsubscribe from sender…
⌃1 … ⌃9	Run Quick Action 1–9
⌘Z	Undo the last change to mail (again for the one before)
⇧⌘Z	Redo
⌘R	Refresh
⌘A	Select all loaded messages
⌘S	Save filter (in Filters)
⌘,	Settings

Settings

• General:
  • mark messages as read when opened (off by default);
  • iCloud: sync quick actions and the account list across your Macs (on by default). Sign-ins and mail never go to iCloud, so on another Mac the accounts show Sign In… until you sign in there once. Signing out of an account on one Mac removes it from the others;
  • Offline cache: how much mail to keep on this Mac (Off, 250 MB … 5 GB; 1 GB by default), how much is in use, and Clear Cache. Lists you've seen show instantly and refresh in the background; messages you've opened, or that were in a list you loaded, open without waiting. Only message text, headers and labels are kept, never attachments.
• Quick Actions: see above.
• Filters: filters grouped by label, with bulk Move to label (see above).
• Accounts: add accounts and sign out. Accounts synced from another Mac show Sign In… and Remove.