Local user guide

## How to use the Email Agent

Start here

This app runs only while this computer is awake and the agent window is open. Configure and test the mailbox before enabling automation.

### 1 Connect an email account

Choose Standard SMTP/IMAP when your provider gives normal mail-server settings. Choose Webmail-hosted account for an address normally opened through Roundcube, cPanel Webmail, or a similar browser portal.

1. Open Connections setup, then choose
   .
2. Select the mailbox connection type.
3. Enter the dedicated email address. The username is usually the complete email address.
4. Enter the mailbox password or provider-issued app password.
5. Enter the outgoing SMTP and incoming IMAP details supplied by the email host.
6. Click Test SMTP, then Test IMAP. Both must succeed.
7. Save the settings. Enable automation only after the connection tests pass.

Purpose | Common secure setting | What it does
--- | --- | ---
SMTP | Port 587 + STARTTLS, or 465 + SSL/TLS | Sends email
IMAP | Port 993 + SSL/TLS | Reads replies

For webmail users: Sign into the webmail portal and look for Configure Mail Client, Connect Devices, Manual Settings, or ask the hosting company for the secure SMTP and IMAP details. Enter those details here. Do not enter the `https://webmail…` browser address into the SMTP or IMAP fields. The provider must allow external mail-client access.

Important: These ports are common, not guaranteed. Use the exact server names, ports, security type, and authentication method supplied by your email provider. If a correct password is rejected, confirm that SMTP/IMAP password access is enabled or obtain an app password.

### 2 Connect external AI (optional)

You do not need AI to use this app. If you leave the AI fields empty, you manage the app yourself and its fixed safety rules still detect likely opt-outs, bounces, and replies.

An external AI provider is a company that runs an AI model on its computers and allows this app to communicate with it over the internet. To make that connection, the provider gives you three pieces of information: an API address, a model name, and a private API key.

Field in this app | Meaning in plain language | Where you normally find it
--- | --- | ---
HTTPS API endpoint | The secure internet address this app calls to reach the provider's AI system. It starts with `https://`. It is not the address of the provider's normal chat webpage. | The provider's official developer or API documentation, usually under “Base URL”, “API endpoint”, or “OpenAI-compatible endpoint”.
Model ID | The model's exact computer-readable code—not the friendly name shown in ChatGPT or another chat app. For example, the display name GPT-5.6 Sol uses the model ID `gpt-5.6-sol`. | Copy the value labelled Model ID from the provider's API model catalogue. Spaces, missing prefixes and changed punctuation will cause the test to fail.
API key | A private password that allows this app to use your provider account and may create billable usage. | Sign in to the provider's official account dashboard and look for “API keys”, “Developer”, or “Credentials”, then create a new secret key.

#### Where to get the details for common providers

These are separate API services. Having a normal ChatGPT or Claude subscription does not automatically create an API key or include this app's usage.

##### OpenAI / ChatGPT

1. Sign in at the official OpenAI API Platform using your OpenAI account.
2. Open API keys and create a secret key.
3. Open the API Platform billing settings and add API credit or a payment method. Your ChatGPT subscription is billed separately.
4. Enter `https://api.openai.com/v1` as the endpoint.
5. Open the official OpenAI API model catalogue. Open a model and copy the value printed under Model ID—not the large friendly title.
6. For routine email management, begin with `gpt-5.6-luna` for lower-cost, higher-volume work or `gpt-5.6-terra` for a stronger balance of judgement and cost. `gpt-5.6-sol` is the high-capability option, but it is not required for ordinary classification and campaign questions.

##### Anthropic / Claude

The native Anthropic API is not currently supported directly by this version of the app because it does not use the required OpenAI-compatible connection format. To use Claude, connect through an OpenAI-compatible service such as OpenRouter and select a Claude model there. A normal Claude Pro or Max subscription does not supply OpenRouter API access.

##### Google Gemini

1. Open the official Google AI Studio API key page.
2. Create or select a Google Cloud project and create a Gemini API key. Confirm the account's billing and usage limits.
3. Enter `https://generativelanguage.googleapis.com/v1beta/openai` as the endpoint.
4. Copy a model ID listed as compatible in Google AI Studio or Google's OpenAI-compatibility documentation.

##### OpenRouter (multiple providers)

1. Create an account at the official OpenRouter website, add credits if required, and create a key under account settings.
2. Enter `https://openrouter.ai/api/v1` as the endpoint.
3. Copy the complete model ID from the OpenRouter model list; it normally includes the provider name.
4. This can provide Claude, OpenAI, Gemini and other models through one compatible connection, but your data passes through OpenRouter and then the selected model provider.

Which OpenAI model should I choose?

`gpt-5.6-luna` is the sensible low-cost starting point for routine categorisation and straightforward questions. Use `gpt-5.6-terra` when replies are more nuanced or you want stronger judgement. Use `gpt-5.6-sol` only when the additional capability justifies the higher usage cost. These are starting recommendations, not guarantees: test the chosen model with representative replies before relying on it.

To confirm the current name, visit the official OpenAI model catalogue, open the chosen model, find Model ID, and copy it exactly. The app's Test external AI button then confirms whether that model is available to your API account.

Do not enter: your ChatGPT or Claude email/password, the address of the normal chat webpage, a Claude Code login, or a key copied from an unofficial website. This app accepts an API key created in the provider's official API account only.

#### What to do, step by step

1. Choose an AI provider that specifically offers an OpenAI-compatible API. This describes the connection format; it does not mean the provider must be OpenAI.
2. Create an account on the provider's official website. Open its API or developer dashboard. Some providers require you to add payment details or prepaid credit before an API key will work.
3. Create a new API key. Copy it immediately and keep it private—the provider may show the full key only once. Never email it or paste it into the AI chat window.
4. In the provider's official documentation, find the OpenAI-compatible base URL. Copy the complete address beginning with `https://`. Do not copy the address of the webpage where you normally chat with the AI.
5. Choose a model in the provider's API catalogue and copy the exact value labelled Model ID. Example: type `gpt-5.6-sol`, not `5.6 Sol`. Do not invent the value from the friendly model name.
6. Open Connections setup, then choose
   . Paste the three values into HTTPS API endpoint, Model ID, and API key.
7. Read and select the permission checkbox. This is required because campaign details, reply text, and your Assistant questions may be sent to that external company.
8. Click Test external AI. A successful message means the key was accepted and the exact model was found. Then click Save settings.
9. Use the AI Assistant chat panel available on every screen and ask a simple question such as “What needs my attention?”

Subscription versus API access: paying for a provider's chat website does not necessarily give this app access. API service is often activated and billed separately. Check the provider's API dashboard for account status, spending limits, and current charges.

If you cannot find the three values: contact the provider and ask: “Do you offer an OpenAI-compatible API? Please give me the HTTPS base URL, instructions for creating an API key, and the exact model IDs available to my account.” If the provider does not offer that interface, it cannot connect to this version of the app.

Protect the key: treat an API key like a bank-card PIN. This app encrypts the saved key for the current Windows user, but the external provider still receives requests and may charge your account. Set a sensible provider spending limit and revoke the key in the provider dashboard if you believe it has been exposed.

The AI classifies replies and powers the in-app Assistant. It may propose a limited action, but the app executes it only after user approval. Unsubscribe, bounce, and automatic-reply safety rules remain deterministic.

External AI agent authority: the provider receives the selected context described by the consent checkbox. The agent can answer questions and propose only Inbox checking, running due emails, pausing a campaign, or starting a campaign. You must approve the proposal inside the AI Assistant. It cannot delete campaigns, reverse opt-outs, change recipients, or send direct replies.

Disconnect AI: open Connections setup and select Disconnect external AI. After you confirm the warning, the app permanently deletes the saved AI endpoint, model, encrypted API key, consent and connection status from this computer. The AI chat is then hidden and the app returns to self-managed mode. Mailbox settings, campaigns and email automation are not removed.

### 3 Create and run a campaign

1. Open
   and select New campaign.
2. Add the campaign name, first-send time, and contacts in `Name, email@example.com` format.
3. Add the initial template and follow-ups. Follow-up delays are whole days from the preceding email.
4. Preview the design, then create the campaign.
5. Enable automation for scheduled operation, or use Run due emails now on the Overview page.

The machine must be on and the app must be running. A matched reply stops that contact's remaining follow-ups.

### 4 Deal with replies

Use
to review replies. You can write a reply, email the available thread and an internal note to a colleague with Hand off, or close the item. Use Check for messages to check IMAP immediately instead of waiting for the next automatic check.

An unsubscribe request globally suppresses that address and cancels pending sends. Reverse it only when classification was genuinely incorrect.

### 5 Status and troubleshooting

- Automation running: scheduled inbox checks and sends are enabled.
- AI off: no endpoint/model is configured; fixed rules still work.
- AI configured: details are saved but have not passed the current connection test.
- AI unavailable: the service, endpoint, or selected model could not be verified.
- Failed jobs: open Campaigns and Activity, correct the mailbox issue, then run due emails again.

Operational command centre

## Overview

Your campaigns, replies and delivery queue at a glance.

Needs attention 0
Active campaigns 0
Pending emails 0
Emails sent 0
Failed jobs 0
Globally opted out 0

### Operating rule

Templates and schedules send automatically. Any matched inbound reply stops the sequence and comes back to you unless it is a deterministic unsubscribe or bounce.

Sequences

## Campaigns

Automation is off. Active campaigns remain queued and will not send automatically. Enable automation under Mailbox, or use “Check and run now” for a manual run.

### Create campaign

Follow-up delays are measured in days from the previous step.

Campaign name First scheduled send
Contacts One per line: Name, email@example.com

### Template sequence

Email preview Sample recipient: Alex Morgan
Subject
You are receiving this email because your contact was included in this campaign. Opt out of future marketing emails or reply with UNSUBSCRIBE.
Activate immediately

No campaigns yet.

Human checkpoint

## Needs attention

No replies need attention.

Required for sending and receiving

## Mailbox connection

01

### Mailbox identity

The account must permit SMTP sending and IMAP receiving.

Connection type
Email address Username Password or app password
Webmail connection

This app connects to the mailbox's SMTP and IMAP services—not to the webmail webpage. Copy the secure manual mail-client settings from the webmail portal or obtain them from the hosting provider.

02

### Outgoing mail (SMTP)

SMTP server Port Security
03

### Incoming mail (IMAP)

IMAP server Port Security
Inbox check interval (seconds)
04

### Email branding

Images are normalized to an email-safe format and embedded in each HTML email. Source image maximum: 5 MB.

Company logoTransparent logos work best. Displayed above the message. Remove saved logo
Signature imageDisplayed below the signature text. Remove saved signature image
Signature text Optional name, position, phone number, website, or disclaimer.

Optional enhancement

## External AI connection

Not required
The Email Agent works without external AI.

Leave this connection disabled to use self-managed mode. Campaign scheduling, sending, Inbox monitoring, opt-outs, replies, handoffs, and fixed safety rules continue to work normally.

AI

### Connect an external provider

This optional connection adds AI classification and the AI Assistant. Need help finding these values? Open ? Help and read “Connect external AI”.

HTTPS API endpoint The provider's secure OpenAI-compatible base address—not its chat webpage. Model ID Exact API code. OpenAI example: gpt-5.6-sol—not “5.6 Sol”. API key Create this private key in the provider's API or developer dashboard.
Choose an OpenAI starting model

Luna suits routine, cost-sensitive email work. Terra offers a stronger balance of judgement and cost. Sol is available for more demanding work but is not normally necessary here. Test with real examples before deciding.

Remove the saved external AI API key I authorize this app to send selected campaign details, reply content, and chat questions to the external AI provider.

Evidence trail

## Recent activity

Time | Event | Details
--- | --- | ---

AI Assistant Connection required
AI Assistant

Ask about campaigns, failures, or replies. I can also propose checking messages, running due emails, or pausing/starting a campaign. Any proposed action requires your approval.