Email

Pass an email-capable piece to buildConfig({ email }) to send authentication emails and application messages. The email option accepts only EmailPiece | Promise<EmailPiece>.

Configure Resend

Install the Resend piece in your FrogBot app:

pnpm add @frogbotai/piece-resend

Set RESEND_API_KEY in your environment, then configure credentials and the default sender on the piece factory:

import { sqliteAdapter } from '@frogbotai/db-sqlite';
import { createResend } from '@frogbotai/piece-resend';
import { buildConfig } from 'frogbot';

const resend = createResend({
  auth: { apiKey: process.env.RESEND_API_KEY! },
  from: { address: 'notifications@example.com', name: 'Acme' },
});

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: sqliteAdapter({ client: { url: 'file:./frogbot.db' } }),
  collections: [],
  email: resend,
});

Option	Type	Default	Description
`slug`	`string`	`'resend'`	Instance slug. It prefixes tool slugs and is the default sender name.
`auth.apiKey`	`string`	Required with `auth`	Resend API key used for application email and the piece’s actions.
`from.address`	`string`	—	Default sender address. Required when this piece is used for `email`.
`from.name`	`string`	The instance slug	Sender display name.

Resend has no OAuth recipe, so the factory does not accept oauth. See factory options. FrogBot uses the factory credentials for application email, including password resets and verification messages. It creates a request without a signed-in user for each send, so user connections do not supply email credentials. Missing factory credentials raise a ConnectionError naming the piece when you send.

Promised configuration

You can also pass a promise that resolves to the piece. With the resend instance above, use email: Promise.resolve(resend) in the config. FrogBot awaits the promise and validates the piece during initialization, before serving requests.

Send email

After FrogBot initializes, call frogbot.email.sendEmail(...) wherever you have a FrogBot instance:

await frogbot.email.sendEmail({
  to: 'customer@example.com',
  subject: 'Your order is confirmed',
  text: 'Thanks for your order. We will email you when it ships.',
});

The default from is formatted as "Acme" <notifications@example.com> using the factory options. An explicit per-message from overrides that default:

await frogbot.email.sendEmail({
  from: { address: 'support@example.com', name: 'Acme Support' },
  to: 'customer@example.com',
  replyTo: 'support@example.com',
  subject: 'Your support request',
  html: '<p>We received your request and will reply shortly.</p>',
});

Resend email supports these options. Recipients can be address strings, { address, name } objects, or arrays of either.

Option	Type	Default	Description
`to`	Recipient or recipients	—	Primary recipients.
`cc`	Recipient or recipients	—	Copied recipients.
`bcc`	Recipient or recipients	—	Blind-copied recipients.
`from`	`string \| { address: string; name?: string }`	The factory `from`	Sender for this message.
`replyTo`	Recipient or recipients	—	Reply-to addresses, sent as Resend’s `reply_to`.
`subject`	`string`	`''`	Subject line.
`html`	`string \| Buffer`	—	HTML body.
`text`	`string \| Buffer`	—	Plain-text body.
`attachments`	`{ filename?: string; content: string \| Buffer; encoding?: string }[]`	—	Files to attach. See Attach files.

sendEmail also accepts the other fields of the standard mail options type, such as headers; the Resend piece ignores them.

Attach files

Provide each attachment’s contents as a string or a Node.js Buffer. FrogBot converts the content to base64 for Resend. Strings use UTF-8 unless you supply an encoding; for an already-base64 string, set encoding: 'base64'.

import { Buffer } from 'node:buffer';

await frogbot.email.sendEmail({
  to: 'customer@example.com',
  subject: 'Your report',
  text: 'Your report is attached.',
  attachments: [
    {
      filename: 'report.csv',
      content: Buffer.from('item,quantity\nNotebook,2\n'),
    },
  ],
});

Streams, local attachment paths, and remote attachment URLs are unsupported. Read or download the file yourself, then pass its contents as a Buffer. An attachment without string or Buffer content throws Piece 'resend' email attachments must be a string or Buffer before a request is sent.

Configuration errors

FrogBot rejects invalid email configuration during initialization. Direct pieces are validated while building the config; promised pieces are validated after they resolve.

Error	Fix
`email must be a piece that implements email`	Pass an email-capable piece instance.
`Piece '<slug>' does not implement email`	Choose a piece with an email capability. TypeScript also rejects pieces without it.
`Piece '<slug>' is used as email but has no from`	Set a non-empty factory sender address, even if your messages override `from`.

Delivery errors

The Resend piece sends a direct fetch request to the Resend API. Non-success responses throw an error such as Resend request failed (422): <message>, using Resend’s message when available and the HTTP status text otherwise. Network failures also reject the send. There are no automatic retries; handle rejected sends in your application.

Without email

If you omit email, FrogBot warns at startup and logs attempts to send email without delivering messages.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Configure Resend

Promised configuration

Send email

Attach files

Configuration errors

Delivery errors

Without email

​Configure Resend

​Promised configuration

​Send email

​Attach files

​Configuration errors

​Delivery errors

​Without email

Configure Resend

Promised configuration

Send email

Attach files

Configuration errors

Delivery errors

Without email