Email

Send builder-defined email content to a specific user from an agent

How Email works

Use Email when you want the agent to execute a preconfigured email action. The agent decides when to use the tool, while you control the sender, subject, and body defaults in the builder. This gives you full control over the messaging content while letting the agent handle timing and recipient selection based on real-time context.

Email is ideal when your copy is already approved and consistent messaging matters more than personalization. Because all content is builder-defined, the agent cannot modify the email body — it simply triggers delivery when conditions are met during the run.

Configuration

Inputs

Prompt · string

Instructions that define when this tool should be used.

Send to (`params.to_id`) · string · required

Flywheel user ID to receive the email.

Sender (`params.sender_config_id`) · string · required

Sender configuration to use for delivery.

Subject (`params.subject`) · string

Subject used for this message.

Preview (`params.preview_text`) · string

Optional email preview text.

CC (`params.cc_emails`) · string[]

Optional CC recipients.

BCC (`params.bcc_emails`) · string[]

Optional BCC recipients.

Complete on send failure (`params.complete_on_send_failure`) · boolean · default: "true"

Whether the run should continue when send fails.

Outputs

status · enum · required

The status of the email send operation. Can be success, failure, or skipped.

to_id · string · required

The ID of the user that the email was sent to.

sender_config_id · string · required

The ID of the sender configuration used for the email.

email_id · string

The ID of the email that was sent (available on success).

create_email_options · object

The options used when creating the email, including subject, preview text, and recipients (available on success).

create_email_response · object

The response from the email creation service (available on success).

code · enum

The code indicating why the email send operation failed or was skipped. Can be resend_error, duplicate_email, or user_marketing_email_opt_out.

error_message · string

The message of the error that occurred (available on failure).

Use cases

Onboarding Completion

Condition: User completed onboarding checklist
Action: Send preconfigured welcome email with next steps
Outcome: User receives consistent onboarding messaging immediately after setup

High-Intent Follow-Up

Condition: Agent classifies user as high intent based on activity signals
Action: Send tailored follow-up using builder-defined template
Outcome: Qualified lead receives timely outreach without manual intervention

Renewal Reminder

Condition: User subscription renewal date is within 14 days
Action: Send renewal reminder email with plan details
Outcome: User is prompted to renew before their subscription lapses

Feature Adoption Nudge

Condition: User has not activated a key feature after 7 days
Action: Send feature education email highlighting benefits and setup guide
Outcome: Drive feature adoption with well-timed product education

Best practices

Content Control

• Keep all email content builder-defined to ensure brand consistency and compliance review.
• Use this tool instead of AI-generated variants when the copy must match an approved template exactly.
• Pair with preview text to improve open rates in inbox clients.

Failure Handling

• Enable complete_on_send_failure when the agent run should proceed even if the email fails.
• Monitor code output values like duplicate_email and user_marketing_email_opt_out to understand skip reasons.
• Log error_message output for debugging delivery issues in BetterStack.

Targeting and Timing

• Use the agent prompt to define clear conditions for when this tool should fire during a run.
• Avoid sending duplicate emails by checking recent send history through agent context.
• Combine with other tools like Set Custom Property to mark users after email delivery.