Skip to content

User Guide

Jump to bottom
Vinayak Pandey edited this page Jul 1, 2026 · 9 revisions

Getting started

Run VinMail:

vinmail

Navigate using ↑ / ↓ or j / k, confirm with Enter, cancel or go back with q.

Adding an account

From the main menu select Add account. VinMail will guide you through:

Alias a short name for the account, e.g. work or personal
Email address your full email address
Display name the name recipients will see in the From field
SMTP preset pick your provider or enter custom SMTP details
Password your app password, stored as plain text or GPG encrypted

Press Esc at any prompt to abort. VinMail will ask for confirmation before cancelling.

Gmail / Google Workspace setup

Gmail does not allow your regular account password for SMTP. You must use an App Password.

  1. Go to your Google Account
  2. Navigate to Security → 2-Step Verification → App Passwords
  3. Generate a password for "Mail"
  4. Use that password when VinMail asks for your app password

Switching accounts

Select Switch active account from the main menu. The currently active account is marked with ★. Selecting an account copies its config to ~/.msmtprc so msmtp uses it for all outgoing mail.

Composing and sending mail

Select Compose & send mail from the main menu. You will see the compose screen:

  From   : Your Name <you@example.com>
  To     : (required)
  Cc     : (none)
  Bcc    : (none)
  Subject: (empty)
  Attach : (none)
  GPG    : (unsigned)
Key Action
t Edit To (editable any time, prefilled when editing)
c Edit Cc (editable any time)
b Edit Bcc (editable any time, not written to headers)
s Edit Subject (editable any time)
e Open body in $EDITOR
a Manage attachments, add by path (Tab completion supported), remove by index
g Toggle GPG signing
d Save as draft
y Preview full body and send
q Discard or exit. If a draft was saved, exits without prompting

Drafts

Press d in the compose screen at any point to save your current message as a draft. All fields are saved: To, Cc, Bcc, Subject, body, attachments, and GPG settings.

From the main menu select Drafts (the count in brackets shows how many drafts are saved). Inside the draft list:

  • Press Enter to open a draft. It reopens the compose screen pre-filled.
  • Press d to delete a draft directly from the list without opening it.
  • Press q to go back to the main menu.

When a draft is sent successfully it is deleted automatically.

Replying to mail

Select Reply to mail from the main menu. VinMail will ask for the path to the original message as a .eml file. Tab completion is supported for the path.

Most mail clients can export a message as .eml:

  • Thunderbird: right-click message → Save As
  • Gmail: open message → More (⋮) → Download message
  • Apple Mail: File → Save As

VinMail parses the original message and shows what it found:

  From    : sender@example.com
  Subject : Project update
  Date    : Mon, 22 Jun 2026 10:00:00 +0000
  Msg-ID  : <abc123@gmail.com>

Then asks:

  [1] Reply to sender only
  [2] Reply all

For reply-all, VinMail includes all original To and Cc recipients in the reply Cc field, filtering out your own address automatically. The compose screen opens pre-filled with the correct To, Cc, Re: subject, and the original body quoted below your cursor position.

Proper In-Reply-To and References headers are added so recipients' mail clients thread the conversation correctly.

Configuring your editor

VinMail uses $EDITOR for composing mail bodies and editing account configs. It falls back to vim if nothing is set.

To change it permanently, add to your ~/.zshrc or ~/.bashrc:

export EDITOR="nano"
export VISUAL="nano"

Then reload:

source ~/.zshrc
# or
source ~/.bashrc

To use VS Code or another GUI editor, add --wait so VinMail waits for you to finish before continuing:

export EDITOR="code --wait"

To set the editor for a single session only:

EDITOR=nano vinmail

Data directory

All VinMail data is stored in:

~/.local/share/vinmail/
├── accounts/
│   ├── work.conf          ← msmtp config (chmod 600)
│   └── work.pass.gpg      ← GPG encrypted password (if used)
├── accounts.list          ← account registry
├── drafts/
│   ├── draft_1719045901.draft  ← draft metadata
│   └── draft_1719045901.body   ← draft body text
├── msmtp.log              ← send log
└── .active                ← current active account alias
~/.msmtprc                 ← copy of active account config
~/.mailrc                  ← seeded on first run

If something goes wrong sending, check the log:

cat ~/.local/share/vinmail/msmtp.log

Clone this wiki locally