GMAP Mail

This guide explains how to send, receive, and manage mail in Astronomo using the GMAP protocol and Misfin for message delivery.

Prerequisites

Before using mail, you need a client certificate (identity) for authentication. If you don't have one yet, create it in Settings (Ctrl+,) under the Certificates tab. See the Certificates guide for details.

You also need access to a GMAP-compatible mail server.

Opening the Mail Screen

Press Ctrl+E to open the mail screen. Press Ctrl+E or Esc to close it and return to browsing.

If you haven't set up a mail account yet, press Ctrl+A to add one.

Setting Up an Account

1. Open the mail screen (Ctrl+E)
2. Press Ctrl+A to add a new account
3. Fill in the account details:

Field	Description
Account Name	Display name for the account
GMAP Server Hostname	Your mail server hostname
Port	Server port (default: 1960)
Mailbox Name	Your mailbox name (from certificate)
Identity	Client certificate to use for authentication
GMAP Address	Address for sent mail copies (default: gmap@hostname)

1. Press Enter to save

Tip

The identity you select must be trusted by the GMAP server. Check with your server administrator if you're unsure which certificate to use.

Switching Accounts

Press Ctrl+L or click the Switch Account button in the mail header to open the account switcher.

1. Select an account from the list
2. Press Enter to switch

The current account is indicated with a > marker. Switching accounts reloads the message cache and syncs from the new account's server.

To remove an account, click the X button next to it in the switcher.

Tip

The Switch Account button only appears when you have more than one account configured.

Reading Messages

Three-Pane Layout

The mail screen has three panels:

Panel	Description
Tags (left)	Tag list with unread counts
Messages (center)	Messages in the selected tag
Message (right)	Full content of the selected message

Navigation

Key	Action
Tab / Shift+Tab	Switch between panels
Left / Right	Switch between panels
Up / Down	Navigate within current panel
Enter	Select tag or message

Viewing a Message

1. Select a tag from the left panel (e.g., Inbox)
2. Use Up / Down to browse messages in the center panel
3. The selected message appears in the right panel with:
   • Sender and recipient addresses
   • Timestamp
   • Tags
   • Full message body (rendered as Gemtext)

Tag Operations

Tags organize your messages. Every account starts with these built-in tags:

• Inbox — New incoming messages
• Archive — Messages you've archived
• Sent — Messages you've sent
• Drafts — Message drafts
• Trash — Messages marked for deletion

Quick Actions

Key	Action
A	Archive selected message (moves from Inbox to Archive)
D	Trash selected message (moves to Trash)
U	Toggle unread status
T	Manage tags (add/remove custom tags)

Custom Tags

1. Select a message
2. Press T to open the tag manager
3. Check or uncheck existing tags
4. Type a new tag name and press the Add button to create a custom tag

Note

Tag names can only contain letters, numbers, underscores, and hyphens.

Deleting Messages

Astronomo uses a two-step delete to prevent accidental data loss:

1. Press D to move a message to Trash
2. Select the Trash tag to view trashed messages
3. Select the message and press Shift+D to permanently delete it
4. Confirm deletion in the dialog

Warning

Permanent deletion cannot be undone. The message is removed from both the local cache and the server.

Composing Messages

1. Press Ctrl+N to open the compose window
2. Enter the recipient address (e.g., alice@example.com)
3. Optionally enter a subject
4. Write your message body in Gemtext format
5. Press Send

The message is sent via the Misfin protocol. A copy is automatically saved to your Sent folder on the GMAP server.

Tip

The message body supports Gemtext formatting: headings (# Title), links (=> url label), lists (* item), and preformatted blocks (```).

Replying to Messages

1. Select a message
2. Press R to reply
3. The compose window opens with:
   • To pre-filled with the original sender's address
   • Subject pre-filled with Re: Original Subject
   • Body pre-filled with the original message quoted using > markers
4. Write your reply and press Send

Misfin Links

Gemtext pages can contain misfin: links that open the compose window with pre-filled fields:

• misfin:alice@example.com — compose to alice
• misfin:alice@example.com?Hello%20there — compose with body text

When you click a misfin: link or enter one in the address bar, the mail compose screen opens automatically.

Syncing

Press Ctrl+R to sync messages from the server. Syncing:

• Fetches new messages since your last sync
• Updates tags for existing messages
• Runs in the background without blocking the UI

The sync status is shown in the mail screen header.

Storage

Account Configuration

Accounts are stored at ~/.config/astronomo/gmap_accounts.toml:

[accounts.uuid-here]
id = "uuid-here"
name = "My Account"
hostname = "mail.example.com"
port = 1960
mailbox = "alice"
identity_id = "cert-uuid"
gmap_address = "gmap@mail.example.com"

Message Cache

Messages are cached locally in an SQLite database at ~/.cache/astronomo/mail_cache.db for fast queries and offline access. The cache stores message content, metadata, and tags.

Keyboard Reference

Mail Screen

Key	Action
Esc or Ctrl+E	Close mail screen
Tab / Shift+Tab	Next / previous panel
Left / Right	Switch panels
Up / Down	Navigate within panel
Enter	Select item
Ctrl+N	Compose new message
Ctrl+R	Sync messages
Ctrl+A	Add account

Message Actions

Key	Action
A	Archive message
D	Move to Trash
Shift+D	Permanently delete (from Trash)
U	Toggle unread
R	Reply
T	Manage tags

Tips

1. Set up your identity first — Create a client certificate before adding a mail account
2. Use tags to organize — Archive messages you've read, use custom tags for projects
3. Sync regularly — Messages don't auto-sync; press Ctrl+R to check for new mail
4. Two-step delete — You must Trash a message (D) before you can permanently delete it (Shift+D)
5. Gemtext formatting — Use headings and links in your messages for rich content