Skip to main content

​
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.