adding email to your botpress agent without oauth

The Botpress email channel setup usually goes like this: you click "Connect Gmail," get redirected to Google Cloud Console, spend 40 minutes creating a project and OAuth credentials, configure a consent screen, add test users, and then wait to see if Google flags your app as unverified. That's if everything goes right.

If something goes wrong — and it often does — you're deep in a Botpress Discord thread at 11pm wondering why your token expired again.

This is the OAuth wall, and it hits almost every Botpress developer who tries to add email to an agent. There's a way around it.

Why email is harder than every other botpress channel#

Slack, WhatsApp, Telegram: you paste a token and it works. Email is the exception because email wasn't designed for autonomous agents. It was designed for humans with accounts.

When you wire Gmail into Botpress, you're authenticating a human Google account via OAuth 2.0. That means someone has to own that account (you, a shared mailbox, or a service account requiring Workspace admin access). The OAuth token refreshes on Google's schedule, not yours. And if Google's systems decide your app looks suspicious — maybe you haven't completed their app verification process — the token breaks and your bot silently stops processing email.

Token expiry in Botpress email integrations is one of the most frequently reported issues in their community Discord. It's not a bug in Botpress. It's the fundamental mismatch between OAuth's design (grant humans access to apps) and what agents actually need (an inbox they own and control directly, with no human in the loop).

For more context on why this pattern keeps causing grief, see why Gmail OAuth is painful for agents and why your agent shouldn't use Gmail at all.

What your agent actually needs from email#

Three email use cases come up repeatedly in Botpress projects.

Follow-up sequences are the most common. A user chats with your bot, drops their email address, and a day later your agent sends a personalized follow-up based on the conversation. This is outbound only, so SMTP can technically handle it — but SMTP still requires mail server setup, domain authentication records, and usually a transactional email account somewhere.

Bidirectional threads are harder. Your agent sends a message, the human replies, and the agent reads that reply and continues the conversation. Simple SMTP breaks down here entirely — you need an inbox the agent can check.

Verification codes are the third case, increasingly relevant as Botpress agents take on more autonomous workflows. If your bot needs to complete a signup or confirm an action via email, it needs an address it can poll for that code on demand.

LobsterMail handles all three. No OAuth, no mail server, no human account standing behind it.

Giving your botpress agent its own inbox#

Install the SDK:

npm install @lobsterkit/lobstermail

In a Botpress code action node, your agent hatches its own inbox:

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'My Botpress Agent' });

console.log(inbox.address); // my-botpress-agent@lobstermail.ai

LobsterMail.create() handles account provisioning on the first run. There's no dashboard to visit, no credentials to configure. The SDK creates a free account, saves an API token locally, and reuses it on every subsequent run. Your agent goes from zero to a working @lobstermail.ai inbox in seconds.

Receiving is one call:

const emails = await inbox.receive();
for (const email of emails) {
  console.log(email.subject, email.preview);
}

Sending uses the same object:

await inbox.send({
  to: 'lead@example.com',
  subject: 'Following up from our chat',
  text: 'Hey, just wanted to circle back on what you mentioned...',
});

No SMTP configuration. Replies come back to the same inbox address automatically.

Wiring it into a botpress flow#

The pattern that works well in practice: a trigger node fires, a code action creates (or reloads) the agent's inbox, your conversation logic runs, another code action sends the follow-up, and a later code action polls for replies.

The inbox address persists between sessions because the token file persists. Create it once, store the address in a workflow variable, and reference it in every subsequent run. You don't need to reprovision.

If you want per-user isolation — each conversation gets its own address so replies route cleanly without any cross-contamination — you can create a fresh inbox per session. The free tier covers 1,000 emails a month. For most lead-gen or support bots, that's more than enough to start.

When volume grows, the Builder plan at $9/month gets you up to 10 inboxes and 5,000 emails monthly.

When oauth is still the right call#

If your bot needs to send from your company domain specifically — because your deliverability is tied to that domain's reputation, or users expect a @yourcompany.com sender — then OAuth to a proper mail account is the right call. The setup pain is real but it's the right tradeoff when branding requires it.

LobsterMail is for agents that need working email fast, without a human account standing behind them. If that matches your situation, this is the shorter path.

Give your agent its own inbox. Get started with LobsterMail — it's free.