# Quick start

## Three commands to a live inbox.

Install, paste a key, start the gateway. If anything is off, `hermes openmail doctor` says what.

```bash
# Install the OpenMail plugin
hermes plugins install openmail --enable

# Paste a key from console.openmail.sh
hermes openmail setup

# Mail now wakes the agent
hermes gateway run
```

## What's included

### Everything the agent needs to work by email.

- maya@northwind.example

#### Which plan covers SSO?

- hermes@omail.sh
- Re: Which plan covers SSO?
- personreply
- automated · marketing · bouncenotify
- spam · maliciousdropped
- ▾ sales
- outreach@omail.sh
- +3 inboxes · 2 domains
- ▾ acme
- support@omail.sh

### Modes

## Pick how your agent handles email.

Channel is the default. Change it [by hand](https://docs.openmail.sh/integrations/hermes#modes) or ask your agent to do it for you.

Tell maya@northwind.example the sandbox is ready.

### Use cases

## What your Hermes agent can do with email.

#### Answer a question by email

Someone writes to the agent's address. Hermes reads the thread and answers in it.

#### Read an invoice, file the numbers

Forward a PDF or any file. OpenMail extracts the text and Hermes acts on it: here, a row in your sheet.

#### Summarise a newsletter to Telegram

Point a notify inbox at your subscriptions. OpenMail tags the mail as marketing and Hermes summarises it to your home channel.

## The plugin or Hermes's built-in email gateway?

Hermes ships with an email gateway that connects to a mailbox you already have, such as a Gmail account with an app password, over IMAP and SMTP. That's [the right choice](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) if you want the agent to work from an existing address. The OpenMail plugin is for when the agent should have an address of its own: the inbox is created through an API, mail is pushed to the agent as it arrives, replies are threaded for you, and you can give the agent a key that only opens its own inbox. You can run both.

## Frequently asked questions.

### 01 How do I give a Hermes agent an email address?

Run `hermes plugins install openmail --enable`, then `hermes openmail setup` and paste an OpenMail API key, then `hermes gateway run`. Setup creates the inbox or picks an existing one, and asks who is allowed to email the agent. Look for "[OpenMail] Connected as <address>" in the gateway log. `hermes openmail doctor` checks the setup if anything is off.

### 02 What does hermes openmail setup do?

Asks for an API key of any scope, picks an inbox or creates one, asks who may email the agent, and writes ~/.hermes/.env. `hermes openmail doctor` checks the result.

### 03 Who can email the agent?

The addresses you list during setup, or whoever OpenMail's [sender rules](https://docs.openmail.sh/concepts/sender-rules) allow. Set allow and block rules per account, pod, or inbox in the [console](https://console.openmail.sh/login) or with `openmail policy` on the CLI. Blocked mail is dropped before the agent sees it.

### 04 Can one agent handle several inboxes?

Yes. Point the plugin at a pod and it runs every inbox in it. The agent can create more inboxes and send from any of them.

### 05 Why a plugin instead of an SDK?

Hermes already has a gateway. The plugin registers OpenMail as a platform, so mail wakes the agent over the gateway's websocket with no polling loop and nothing pasted into a prompt. The API key lives in the tools, not the model context.

## Every Hermes agent deserves its own inbox.

Three commands, and your agent answers its own mail.
