Email and SMS campaigns tools

search_email_campaigns: List the email campaigns in a project, or fetch one by ID.
search_sms_campaigns: List the SMS and MMS campaigns in a project, or fetch one by ID.
generate_email_campaign_preview_link: Get a shareable browser URL that shows how an email campaign renders.
create_email_campaign: Create a new email campaign as a draft.
update_email_campaign: Replace the full definition of a draft or inactive email campaign.
delete_email_campaign: Permanently delete a draft or inactive email campaign.
create_sms_campaign: Create a new SMS or MMS campaign as a draft.
update_sms_campaign: Replace the full definition of a draft or inactive SMS or MMS campaign.
delete_sms_campaign: Permanently delete a draft or inactive SMS or MMS campaign.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Marketing dashboard, actions your users or agents take with these tools can have a substantial impact on your campaigns, automations, and customer communications. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

search_email_campaigns

Searches the email campaigns in a project, or fetches one by ID. Email campaigns send one-time or event-triggered emails to customers who match a filter. Omit campaign_id to list all email campaigns as summary records: name, status (draft, active, or inactive), tags, archived flag, and whether the campaign is paused. Schedule, customer filter, email design, and A/B split configuration are excluded from the list.

Pass campaign_id to fetch the full definition of a single campaign, including the schedule, customer filter, A/B split with all variants, silent hours, consent settings, frequency policy, recipient configuration, and throughput policy. To avoid large response sizes, the beefree_template and jinja_html fields are stripped from each variant's design by default. Pass include_design=True to receive the full template content, which is useful when auditing or copying template HTML across projects.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str \| null`	No	The email campaign ID. Omit to list all; provide to fetch one.
`include_design`	`bool`	No	When fetching a single campaign, include the `jinja_html` and `beefree_template` fields. Stripped by default to avoid large responses. Ignored when `campaign_id` is omitted. Defaults to `false`.

Response parameters

The tool returns an EmailCampaignsResponse when campaign_id is omitted, or an EmailCampaignResponse when it's provided.

The EmailCampaignsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[EmailCampaignSummary]`	The email campaigns defined in the project.
`error`	`str \| null`	Error message if the request failed.

The EmailCampaignSummary object has the following fields:

Field	Type	Description
`id`	`str`	The email campaign's unique ID.
`name`	`str`	The campaign's display name.
`status`	`str`	One of `draft`, `active`, or `inactive`.
`is_paused`	`bool`	Whether the campaign is paused.
`archived`	`bool`	Whether the campaign has been archived.
`tags`	`list[str]`	User-defined tags.
`company_id`	`str`	The project ID this campaign belongs to.
`scenario_id`	`str \| null`	The ID of the underlying system scenario.
`created`	`any \| null`	Unix timestamp of when the campaign was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`initiative_id`	`str \| null`	The initiative this campaign belongs to, if any.
`is_global_object`	`bool`	Whether the campaign is a global, shared object.
`locked`	`bool`	Whether the campaign is locked by access groups.
`locked_for_current_user`	`bool`	Whether the current user is locked out of editing.

When campaign_id is provided, the tool returns an EmailCampaignResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`EmailCampaign \| null`	The full email campaign record.
`error`	`str \| null`	Error message if the request failed.

The EmailCampaign object adds the following fields on top of the summary record:

Field	Type	Description
`schedule`	`any \| null`	The trigger and schedule. `type='now'` sends immediately; `type='datetime'` sends at a fixed time; `type='event'` triggers on a customer event; `type='optimal_time'` uses an ML-predicted optimal send time.
`customer_filter`	`any \| null`	The conditions that decide which customers receive the campaign.
`split`	`any \| null`	The A/B test configuration. `type='off'` means a single variant; other values are `manual`, `auto-winner`, and `contextual` (bandits). Each variant contains an email design.
`design`	`any \| null`	The email design of the first variant. For multi-variant campaigns, use `split.variants[0].design`. The `beefree_template` and `jinja_html` fields are stripped.
`silent_hours`	`any \| null`	The silent hours configuration. Sends that fall inside quiet hours are delayed.
`consent_category`	`str \| null`	The GDPR consent category required to send to a customer.
`consent_category_tracking`	`str \| null`	The consent category for tracking pixels and click events.
`general_consent`	`bool`	Whether the campaign uses the general consent category.
`frequency_policy`	`str \| null`	The ID of the frequency policy applied to this campaign.
`recipient_name`	`str \| null`	The recipient name template. May use Jinja2.
`recipient_email`	`str \| null`	The recipient email address template. May use Jinja2.
`communication_type`	`str \| null`	The communication type code used for consent and compliance routing.
`throughput_policy`	`any \| null`	The rate-limiting policy for this campaign.

search_sms_campaigns

Searches the SMS and MMS campaigns in a project, or fetches one by ID. SMS campaigns send one-time or event-triggered text messages to customers. Omit campaign_id to list all SMS campaigns as summary records: name, status, tags, archived flag, schedule, customer filter, and A/B split. The message content itself (the action field, with variants and translations) is excluded from the list.

Pass campaign_id to fetch the full definition of a single campaign, including the action field with all message variants (each with type of sms or mms, translations keyed by language code, and sender configuration), plus the frequency policy, consent settings, URL params, and throughput policy.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str \| null`	No	The SMS campaign ID. Omit to list all; provide to fetch one.

Response parameters

The tool returns a SmsCampaignsResponse when campaign_id is omitted, or an SmsCampaignResponse when it's provided.

The SmsCampaignsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[SmsCampaignSummary]`	The SMS campaigns defined in the project.
`error`	`str \| null`	Error message if the request failed.

The SmsCampaignSummary object has the following fields:

Field	Type	Description
`id`	`str`	The SMS campaign's unique ID.
`name`	`str`	The campaign's display name.
`status`	`str`	One of `draft`, `active`, or `inactive`.
`is_paused`	`bool`	Whether the campaign is paused.
`archived`	`bool`	Whether the campaign has been archived.
`tags`	`list[str]`	User-defined tags.
`company_id`	`str`	The project ID this campaign belongs to.
`scenario_id`	`str \| null`	The ID of the underlying system scenario.
`created`	`any \| null`	Unix timestamp of when the campaign was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`initiative_id`	`str \| null`	The initiative this campaign belongs to, if any.
`is_global_object`	`bool`	Whether the campaign is a global, shared object.
`schedule`	`any \| null`	The trigger and schedule. `type` is `now`, `event`, `datetime`, or `optimal_time`.
`customer_filter`	`any \| null`	The conditions that decide which customers receive the campaign.
`split`	`any \| null`	The A/B split configuration.
`silent_hours`	`any \| null`	The silent hours configuration.

When campaign_id is provided, the tool returns an SmsCampaignResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`SmsCampaign \| null`	The full SMS campaign record.
`error`	`str \| null`	Error message if the request failed.

The SmsCampaign object adds the following fields on top of the summary record:

Field	Type	Description
`action`	`any \| null`	The message definition. Contains the `variants` list (each with `type` of `sms` or `mms`, `translations` keyed by language code, and sender configuration), `frequency_policy`, `consent_category`, `consent_category_tracking`, `general_consent`, `transfer_user_identity`, `url_params`, and `custom_event_properties`.
`locked`	`bool`	Whether the campaign is locked by access groups.
`locked_for_current_user`	`bool`	Whether the current user is locked out of editing.
`throughput_policy`	`any \| null`	The rate-limiting policy for this campaign.

generate_email_campaign_preview_link

Returns a shareable browser URL that shows how an email campaign renders. Despite the generate in its name, this tool is read-only. It renders the campaign's existing design and changes nothing in the project. Reach for it when you want to check a subject line, a layout, or a Jinja block before a campaign goes out, or to send a rendered proof to someone without Marketing access.

Pass customer_id to resolve personalization tokens against a real customer's data, or omit it for a generic sample render. On A/B campaigns, variant_index picks which variant to render, and language selects a translation on multilingual campaigns. The returned link is publicly accessible without authentication and stays valid for a limited time, so treat it as sensitive whenever the render includes customer data. Errors, such as an unknown campaign ID or a variant with no renderable HTML body, come back as success: false with the detail in error.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str`	Yes	The email campaign ID returned by `search_email_campaigns`.
`variant_index`	`int`	No	The zero-based index of the A/B variant to render. Defaults to `0`, the first variant.
`customer_id`	`str \| null`	No	The internal customer ID to render personalization tokens against. Omit for a generic sample customer.
`language`	`str \| null`	No	The language code for a multilingual campaign, for example `en` or `de`. Omit to use the default language.

Response parameters

The tool returns an EmailCampaignPreviewLinkResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the preview link was generated.
`link`	`str \| null`	The public browser URL for the rendered preview. Valid for a limited time.
`error`	`str \| null`	Error message if the preview link couldn't be generated.

create_email_campaign

Creates a new email campaign. The campaign is always created as a draft — no email is sent until it is activated in the Marketing UI. On success, the tool returns the ID of the new campaign.

The payload requires a name, a schedule (immediate, scheduled, or event-triggered), and a split that holds one or more variants, each carrying an email design with a sender, subject, and content. You can also set a customer_filter, frequency_policy, consent_category, recipient_name, and recipient_email. Consent settings matter here: when general email consent is off, a consent_category is required, so check your project's consent configuration before you build the payload.

Pass customer_filter as an inline object with filters and formula keys. The API doesn't resolve a saved filter referenced as {"id": "..."} — the unknown key is dropped and the campaign goes to every customer. To reuse a saved filter, fetch it with search_customer_filters, then copy its filters and formula values into the payload.

Validation failures from the Marketing backend, such as a missing consent category or an invalid schedule type, come back as success: false with the HTTP status and the backend's response body in error. That tells you which field to correct before you retry.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`payload`	`dict`	Yes	The campaign definition. Requires `name`, `schedule`, and `split`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the newly created campaign.
`error`	`str \| null`	The HTTP status and the backend's validation detail if the operation failed.

update_email_campaign

Replaces the full definition of an existing email campaign with the payload you provide (PUT semantics), so pass the complete campaign, not just the fields you want to change. The typical workflow is to fetch the current definition with search_email_campaigns, modify the fields you need, then pass the whole modified object here. The campaign must be in draft or inactive status — active and paused campaigns cannot be updated. Status and archived flags are preserved from the existing campaign regardless of what you pass, so activation still happens in the Marketing UI.

Find campaign IDs with search_email_campaigns. As with create, a rejected payload comes back as success: false with the HTTP status and the backend's validation detail in error.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str`	Yes	The email campaign ID returned by `search_email_campaigns` or `create_email_campaign`.
`payload`	`dict`	Yes	The full updated campaign definition, in the same shape as create.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the updated campaign.
`error`	`str \| null`	The HTTP status and the backend's validation detail if the operation failed.

delete_email_campaign

Permanently deletes an email campaign. The campaign must be in draft or inactive status — active and paused campaigns cannot be deleted. This action is irreversible: the campaign and its associated system scenario are removed, and there is no undo through this tool, so verify the target before you run it.

Find campaign IDs with search_email_campaigns. A refused delete comes back as success: false with the HTTP status and the backend's message in error, so you can see why the campaign was protected.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str`	Yes	The email campaign ID returned by `search_email_campaigns`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	Not present for deletes.
`error`	`str \| null`	The HTTP status and the backend's message if the delete failed.

create_sms_campaign

Creates a new SMS or MMS campaign. The campaign is always created as a draft — no message is sent until it is activated in the Marketing UI. On success, the tool returns the ID of the new campaign.

The payload requires a name, a schedule (immediate, scheduled, or event-triggered), a split for variant configuration, and an action that holds the message content. Each message variant carries translations keyed by language code, along with sender configuration. Both sender.name and sender.sender are required, and sender.sender must be 1 to 11 alphanumeric characters or a phone number, such as +15551234567. Because SMS has strict character limits and opt-out language requirements, review your message content before you build the payload.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`payload`	`dict`	Yes	The campaign definition. Requires `name`, `schedule`, `split`, and `action`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the newly created campaign.
`error`	`str \| null`	Error or validation detail if the operation failed.

update_sms_campaign

Replaces the full definition of an existing SMS or MMS campaign with the payload you provide (PUT semantics), so pass the complete campaign, not just the fields you want to change. The typical workflow is to fetch the current definition with search_sms_campaigns, modify the fields you need, then pass the whole modified object here. The campaign must be in draft or inactive status. Status transitions are not exposed here — activate a campaign in the Marketing UI.

Find campaign IDs with search_sms_campaigns.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str`	Yes	The SMS campaign ID returned by `search_sms_campaigns` or `create_sms_campaign`.
`payload`	`dict`	Yes	The full updated campaign definition, in the same shape as create.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the updated campaign.
`error`	`str \| null`	Error or validation detail if the operation failed.

delete_sms_campaign

Permanently deletes an SMS or MMS campaign. The campaign must be in draft or inactive status — active campaigns cannot be deleted. This action is irreversible, and there is no undo through this tool, so verify the target before you run it.

Find campaign IDs with search_sms_campaigns.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`campaign_id`	`str`	Yes	The SMS campaign ID returned by `search_sms_campaigns`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	Not present for deletes.
`error`	`str \| null`	Error detail if the operation failed.