Getting Started

What is Mailgator?

Mailgator is a transparent IMAP and SMTP proxy that sits between your email client and your mail server. It enforces access control rules so you can decide exactly which emails can be read, sent, moved, or deleted -- before they ever reach the server.

Whether you're protecting a shared mailbox, restricting an AI agent's access, or adding human approval to outgoing emails, Mailgator gives you fine-grained control without changing your email provider.

Prerequisites

  • An email account with IMAP and SMTP access (Gmail, Outlook, Fastmail, any provider)
  • A terminal / command line (macOS Terminal, Windows PowerShell, Linux shell)
  • A Mailgator account at mailgator.io

Step 1: Install Mailgator

Download the binary for your platform from the releases page:

# macOS (Apple Silicon)
curl -L https://github.com/mailgator/mailgator/releases/latest/download/mailgator-darwin-arm64 -o mailgator
chmod +x mailgator
sudo mv mailgator /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/mailgator/mailgator/releases/latest/download/mailgator-darwin-amd64 -o mailgator
chmod +x mailgator
sudo mv mailgator /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/mailgator/mailgator/releases/latest/download/mailgator-linux-amd64 -o mailgator
chmod +x mailgator
sudo mv mailgator /usr/local/bin/

If you have Go installed, you can also install directly:

go install github.com/mailgator/mailgator@latest

Step 2: Create Your Account

Head to mailgator.io and create a free account. You will need this to activate your license in a later step.

Step 3: Create a Config File

Mailgator uses a TOML configuration file. Generate the template with:

mailgator config init

This creates mailgator-config.toml in your current directory with commented-out examples for every option.

Step 4: Edit Your Config

Open mailgator-config.toml in any text editor and fill in your email server details. Here is a minimal example for Gmail:

[smtp]
upstream_addr = "smtp.gmail.com:587"
listen_addr = "127.0.0.1:1587"

[imap]
upstream_addr = "imap.gmail.com:993"
listen_addr = "127.0.0.1:1993"

[[rules]]
name = "Allow reading all emails"
action = "allow"
operations = ["read"]

[[rules]]
name = "Allow sending emails"
action = "allow"
operations = ["mail:send"]

[[rules]]
name = "Deny everything else"
action = "deny"

This config lets you read emails and send messages, but blocks deleting, moving, or modifying anything. You can adjust the rules to match your needs -- see the Rules page for details.

Step 5: Activate Your License

Log in through your browser to connect your Mailgator account:

mailgator license login

This opens your browser, lets you sign in at mailgator.io, and automatically saves your license token. The terminal will confirm once authentication is complete.

Step 6: Start the Proxy

Launch the proxy with:

mailgator serve

Mailgator will validate your config, check that the upstream servers are reachable, verify your license, and start listening for IMAP and SMTP connections. You will see output like:

smtp listening on 127.0.0.1:1587 -> smtp.gmail.com:587
imap listening on 127.0.0.1:1993 -> imap.gmail.com:993

Step 7: Point Your Email Client to the Proxy

In your email client (Thunderbird, Apple Mail, Outlook, etc.), update the server settings to point at Mailgator instead of directly at your provider:

IMAP Server

127.0.0.1

IMAP Port

1993

SMTP Server

127.0.0.1

SMTP Port

1587

Use the same username and password as before. Mailgator passes your credentials through to the upstream server -- it does not store or cache them (unless you use the Ask & Approval flow).

What's Next?

Configuration