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

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.