Email Bridge

The Email bridge connects Hefty to an email account, allowing users to send emails that are relayed into Hefty as conversations. Hefty processes the incoming email and sends a response back to the sender.

Prerequisites

  • An email account with IMAP access for receiving messages.
  • SMTP credentials for sending responses.
  • For Gmail accounts, you need to set up Google OAuth2 (see below).

Configuration

Open User Menu → Chat Bridges, select the Email tab, and fill in the following fields:

  • IMAP Server — the hostname of your incoming mail server (e.g., imap.gmail.com).
  • SMTP Server — the hostname of your outgoing mail server (e.g., smtp.gmail.com).
  • Username — the email address used to log in.
  • Password / App Password — the credential for authentication. This field is masked by default.
Protect Your Credentials

Email credentials are sensitive. Never share them in logs, screenshots, or unencrypted messages.

Testing the Connection

After entering your email settings, click the Test button to verify the connection. On success, you'll see a confirmation that the IMAP and SMTP connections are working. On failure, an error message will describe what went wrong (e.g., invalid credentials, server unreachable, authentication method not supported).

How It Works

Once the bridge is running, incoming emails are polled from the configured IMAP mailbox and relayed into Hefty as bridge conversations. These conversations appear in the Conversations sidebar with an EM source badge.

Hefty processes the incoming email through its normal cognition pipeline and sends the response back to the sender's email address. Each sender is tracked individually, so conversations remain separate.

Google OAuth2 Setup

For Gmail accounts, Hefty supports Sign in with Google via OAuth2, which is more secure than using an app password. To use this feature, you need to configure Google OAuth2 credentials before starting Hefty.

Setting Environment Variables

Set the following environment variables before starting Hefty:

export HEFTY_GOOGLE_CLIENT_ID="your-google-client-id"
export HEFTY_GOOGLE_CLIENT_SECRET="your-google-client-secret"
export HEFTY_GOOGLE_REDIRECT_URI="http://localhost:5173/api/v1/bridges/email/google-auth/callback"  # optional
Default Redirect URI

The HEFTY_GOOGLE_REDIRECT_URI variable is optional. If omitted, it defaults to http://localhost:5173/api/v1/bridges/email/google-auth/callback. Only set this if your Hefty instance is hosted on a different domain or port.

Obtaining Google OAuth2 Credentials

To obtain the Client ID and Client Secret:

  1. Go to Google Cloud Console.
  2. Create a new project or select an existing one.
  3. Navigate to APIs & Services → Credentials → Create Credentials → OAuth client ID.
  4. Set the Application type to Web application.
  5. Add an Authorized redirect URI matching your HEFTY_GOOGLE_REDIRECT_URI value (or the default http://localhost:5173/api/v1/bridges/email/google-auth/callback).
  6. Copy the Client ID and Client Secret into the environment variables above.
Important

After setting the environment variables and restarting Hefty, the Sign in with Google button will return the OAuth authorization URL instead of a 400 error. If you still see a 400 error, verify that the redirect URI in Google Cloud Console exactly matches the one configured in Hefty.

Message Flow

  1. A user sends an email to the configured email address.
  2. The Email bridge polls the IMAP mailbox and detects the new message.
  3. The message is relayed into Hefty and processed as a bridge conversation.
  4. Hefty's response is sent back to the sender via SMTP.