Skip to main content

​
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

Inputs

​
Prompt
string
Tool-level instruction that explains when this tool should be used.
​
Send to (`params.to_id`)
string
required
Recipient org user id. Can be provided by user selection or agent decision.
​
From (`params.sender_config_id`)
string
required
Sender configuration used for delivery.
​
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"
Controls whether the run should continue if sending 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, body, and recipient details (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

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.