Using peep

Getting started

peep works with any mailbox that offers IMAP for reading and SMTP for sending. That covers Gmail, AOL, Verizon, Yahoo, iCloud, Outlook.com and nearly every hosting provider or self-run mail server. POP3 isn't supported.

Adding a mailbox

1. Open Settings → Mailboxes → Add a mailbox.
2. Type the email address. For the providers above, the IMAP and SMTP servers fill themselves in.
3. Enter the password. Most big providers need an app password.
4. Optionally pick a color for the mailbox and write a signature.
5. Click Test & save. peep signs in to both servers before saving, and tells you which one failed if either does.

For other servers, fill in the hosts and ports yourself. IMAP is usually port 993 with SSL. SMTP is usually 465 with SSL or 587 with STARTTLS; if 465 fails, peep tries 587 on its own.

The window

The sidebar on the left lists your mailboxes. Each has Inbox, Sent, Spam, Drafts and Trash; subfolders of Inbox sit under it, and everything else is under More folders. The dot next to each mailbox shows whether push mail is connected.

The middle column is the message list, and the right is the reading pane. Drag the dividers to resize them. Turn the reading pane off for a folder with the Pane button or P: the list then shows From, Subject and Date in columns, and messages open full-width or in their own window.

The theme button at the top of the sidebar steps through Dark, Classic, Grey and Light. At the bottom of the sidebar are Settings, the address book and Lock.

Reading

HTML messages are shown on a white page in every theme, with the sender's own styling. Wide newsletters scale down to fit. Plain-text messages use your theme's colors, with clickable links and muted quoted lines.

Remote images

Many newsletters load their pictures from the sender's server, which tells the sender you opened the message. With Load remote images turned off in Settings, peep shows a banner instead and you can click Load images for messages you trust. Pictures attached to the message itself always show.

Links and attachments

Web links open in your normal browser. mailto: links open a new message. Anything else is refused. Scripts, forms and embedded frames in messages are removed before the message is shown.

Click an attachment to open it or save it. Programs and scripts (.exe, .bat, .js and similar) can only be saved, not opened from peep.

The contact card

Click the sender or any recipient in a message header. From the card you can write to them, copy the address, add them to the address book or to an existing contact, list all their messages, or make a rule for them.

Writing

You write in plain text. peep sends it as plain text plus a matching HTML version, so links are clickable and quoted text gets a quote bar in other people's mail programs.

• Cc and Bcc appear when you click them.
• Suggestions appear as you type an address: your contacts first, then people you've written to. Use ↑ ↓ and Enter or Tab to pick.
• Attachments: click the paperclip or drag files in. The limit is 35 MB per message on Windows; many providers allow less, so peep warns past 20 MB.
• Drafts save a few seconds after you stop typing, and with Ctrl+S. Each save replaces the last, so you keep one draft per message. Open a draft to keep writing; sending it removes the draft.
• Closing with changes asks whether to save the draft, discard it or keep writing.
• Signatures are set per mailbox. Change the From address and the signature changes with it.

Before sending, peep asks if the subject is empty, or if your text mentions an attachment and none is attached.

Rules

Rules sort new mail as it arrives in a mailbox's Inbox. Open them from Settings → Rules, from a mailbox's right-click menu, or from a message with ⋮ → Make a rule for this sender…

A rule says: when From, To, Subject or Body contains some text, then move the message to a folder, mark it read, flag it, or any mix of those. Matching ignores upper and lower case and matches part of a word. Your mail server does the matching, so Body rules work without downloading each message.

• Rules are checked from the top. The first one that matches wins. Reorder them with the arrows.
• Run on inbox now applies the rules to mail that's already in the Inbox and reports how many messages moved where.
• Each rule shows how many messages it has matched, and has an on/off switch.

Folders

Right-click a folder, or a mailbox's name, for folder actions:

• New folder and New subfolder.
• Rename. Subfolders, and rules that move mail into the folder, follow the new name.
• Delete. The confirmation says how many messages go with it and which rules stop moving mail there. Rules with nothing else to do are switched off.
• Mark all as read, and Empty Trash or Empty Spam, which are permanent.

Inbox, Sent, Drafts, Spam and Trash can't be renamed or deleted.

Search

Typing in the search box filters the messages already loaded in the list. Press Enter to search the whole folder on your mail server instead. Every word has to match; put "words in quotes" to match them as a phrase. A banner shows how many messages matched, with the newest 200 listed. Esc clears the search.

Address book

Open it with Ctrl+B or the book button at the bottom of the sidebar. Each contact has a name, any number of email addresses, a phone number, a company and notes. Changes save when you switch contacts or close the window.

Importing contacts

Export your contacts from your old mail service as vCard (.vcf) or CSV, then choose Import. peep reads the exports from Gmail, Outlook (including its Unicode CSV), AOL, Yahoo and iCloud. Contacts are matched by email address: existing contacts only get missing details filled in, and your own edits are never overwritten.

Exporting

Choose vCard for other mail programs and phones, or CSV for Excel and Outlook.

On the web, the address book is stored on your server and shared by every browser. On Windows, it's stored on the PC, or shared with your server when the PC is linked.

Linking Windows to your server

If you run peep web, the Windows app can show mailboxes from your server instead of logging in to your mail providers itself. Your server keeps fetching mail while the PC is off, and the PC catches up when it opens.

An example

The PC has mailboxes A, B and C. The server has B, C, D and E. You link the PC and tick B, C and D. The PC now shows its own A, plus B, C and D from the server. Its own copies of B and C switch off, because the server's B and C replace them. The web app still shows B, C, D and E.

Linking

1. In the Windows app: Settings → Server → Link to a server…
2. Type the server's address and your web PIN. The PIN is used once; the PC gets its own key.
3. Tick the mailboxes this PC should show. A server mailbox with the same address as one on the PC is marked as replacing it.

When you link, each replaced PC mailbox's signature and rules are copied up to the server, unless the server already has its own. The two address books are merged by email address.

Day to day

• Everything goes through the server for server mailboxes: reading, sending, moving, deleting, folders and drafts. The PC has no password for them.
• A cloud icon marks server mailboxes in the sidebar. Green means live. Amber means the server can't be reached and you're working from the PC's copy.
• Offline, you can still read, send, move, delete, flag and write drafts. These queue up and go out in order when the server is back. If one no longer applies, for example the message was already deleted on the web, it's dropped with a short notice. Creating, renaming or deleting folders and editing a server mailbox's rules need the server to be reachable.
• The PC keeps 90 days of mail by default (30, 180 and 365 are options): everything received or sent in that window, plus older messages you've opened. Older mail downloads when you open it.

Choosing mailboxes again, or unlinking

Settings → Server → Choose mailboxes… lets you tick or untick mailboxes at any time. Unticking one removes just that mailbox and its downloaded mail from the PC; its PC copy, if there is one, can then be switched back on.

Unlink removes every server mailbox and its downloaded mail from the PC and cancels the PC's key. The PC's own copies stay switched off until you turn them back on in Settings → Mailboxes. You can also sign a PC out from the web app under Settings → Devices; it will ask to link again.

Active, inactive and local data

In Settings → Mailboxes every mailbox has an Active checkbox. An inactive mailbox is hidden from the sidebar but keeps its settings and mail. Delete local data clears what's stored on this PC for a mailbox, which is handy for old copies after linking. The mail on your mail server and on your peep server isn't touched.

PIN and devices

Every browser and every PC has to enter a PIN. Once entered, that device stays unlocked for 14 days, and each use starts the 14 days over. After five wrong PINs in a row, new logins are refused until the lockout is cleared; devices that are already unlocked keep working.

• Web: the web PIN is set on the server with mailctl.php setpin. Setting it signs out every browser; linked PCs stay linked. See signed-in browsers and linked PCs under Settings → Devices.
• Windows: the PC has its own PIN, which can differ from the web PIN. Lock it any time with Ctrl+L. To reset it, run peep.exe --reset-pin.

Keyboard shortcuts

Press ? in the app to see these at any time. Single-letter keys don't fire while you're typing in a text box. In a browser, keys the browser keeps for itself, such as Ctrl+N, Ctrl+L and F5, are left alone.

Server console tool

peep web is managed from the server's shell with bin/mailctl.php. Run it as root:

php /var/www/html/_mail/bin/mailctl.php status

Settings such as the session length, the number of PIN attempts and the upload limit are in _mail/config.php.

Troubleshooting

"Login failed" for AOL, Verizon, Yahoo, Gmail or iCloud

These providers refuse your normal password from mail programs. Make an app password and use that.

New mail doesn't show up until I refresh (web)

The push service is probably not running. Check it with:

systemctl status mail-push --no-pager && journalctl -u mail-push -n 30 --no-pager

Settings → Rules also says whether the push service is running.

Verizon mail is late, or old mail is missing

Verizon's server only shows its newest 10,000 messages to mail programs, and announces new mail late. peep checks every minute as well as listening, so late mail still arrives within about a minute.

Locked out after too many wrong PINs

Web: run php …/_mail/bin/mailctl.php unlock on the server. Windows: run peep.exe --reset-pin.

A device was lost

Sign it out from Settings → Devices in the web app, or sign out every browser with mailctl.php revoke. For a lost PC that wasn't linked, change the passwords of its mailboxes at your providers.

Folder names with accents show as odd characters (web)

The server's PHP is missing the UTF7-IMAP encoding in mbstring. mailctl.php check shows it. Install the full mbstring package for your PHP version.

The Windows app shows an amber cloud

It can't reach your peep server. You can keep working; your actions are queued and sent when the server is back.