> ## Documentation Index
> Fetch the complete documentation index at: https://flywheel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Marketing Email Tool
> Send builder-defined marketing emails from an agent run
## How Marketing Email works
The **Marketing Email** tool sends a marketing email to a user using content and sender defaults configured in the builder. The agent decides *when* to use the tool and *who* to send to, making it ideal for campaign-style messaging where copy is pre-approved but delivery timing depends on user behavior.
Because the content is fully builder-defined, Marketing Email ensures brand consistency across all sends. The agent's role is limited to selecting the right moment and recipient, keeping your campaign messaging on-brand while still reacting to real-time signals during the run.
## Configuration
Tool-level instruction that explains when this tool should be used.
Recipient org user id. Can be provided by user selection or agent decision.
Sender configuration used for delivery.
Optional CC recipients.
Optional BCC recipients.
Controls whether the run should continue if sending fails.
The status of the email send operation. Can be `success`, `failure`, or `skipped`.
The ID of the user that the email was sent to.
The ID of the sender configuration used for the email.
The ID of the email that was sent (available on success).
The options used when creating the email, including subject, body, and recipient details (available on success).
The response from the email creation service (available on success).
The code indicating why the email send operation failed or was skipped. Can be `resend_error`, `duplicate_email`, or `user_marketing_email_opt_out`.
The message of the error that occurred (available on failure).
## Use cases
**Product Launch Announcement**
```
Condition: User is on a qualified trial and matches target segment
Action: Send launch announcement with feature highlights and upgrade CTA
Outcome: Trial users receive timely awareness of new capabilities
```
**Usage Milestone Campaign**
```
Condition: Product usage reaches a defined threshold (e.g., 100 API calls)
Action: Send campaign email celebrating the milestone with next-level tips
Outcome: Engaged users receive contextual encouragement to deepen adoption
```
**Retention Campaign**
```
Condition: User has been inactive for 14+ days
Action: Send re-engagement email with value reminders and return incentive
Outcome: At-risk users receive win-back messaging before churn
```
**Upgrade Promotion**
```
Condition: Free-tier user hits plan limits or requests a gated feature
Action: Send targeted upgrade email with plan comparison and discount offer
Outcome: High-intent free users receive conversion messaging at peak interest
```
## Best practices
**Campaign Consistency**
* Keep all campaign copy and branding builder-defined to maintain consistency across sends.
* Let the agent control timing and recipient selection, not the core copy or design.
* Use preview text to improve open rates and reinforce the subject line in inbox clients.
**Failure Handling**
* Set `complete_on_send_failure` to `true` when the agent run should continue even if the email fails.
* Check the `code` output for `user_marketing_email_opt_out` to understand opt-out-related skips.
* Use `error_message` alongside `code` to diagnose delivery failures and improve reliability.
**Recipient Targeting**
* Define clear trigger conditions in the agent prompt to avoid sending to unqualified users.
* Leverage user properties and event data to let the agent select the best recipients dynamically.
* Avoid duplicate sends by combining with Set Custom Property to mark users who have already received the campaign.