---
updatedAt: 2026-09-17T18:41:17.000Z
agentTools:
siteIndex: https://documentation.bloomreach.com/llms.txt
projectIndex: https://documentation.bloomreach.com/loomi-connect/llms.txt
---
# Email and SMS campaigns tools
* [search\_email\_campaigns](#search_email_campaigns): List the [email campaigns](https://documentation.bloomreach.com/engagement/docs/working-with-emails) in a project, or fetch one by ID.
* [search\_sms\_campaigns](#search_sms_campaigns): List the [SMS and MMS campaigns](https://documentation.bloomreach.com/engagement/docs/sms-and-mms) in a project, or fetch one by ID.
* [generate\_email\_campaign\_preview\_link](#generate_email_campaign_preview_link): Get a shareable browser URL that shows how an email campaign renders.
* [create\_email\_campaign](#create_email_campaign): Create a new email campaign as a draft.
* [update\_email\_campaign](#update_email_campaign): Replace the full definition of a draft or inactive email campaign.
* [delete\_email\_campaign](#delete_email_campaign): Permanently delete a draft or inactive email campaign.
* [create\_sms\_campaign](#create_sms_campaign): Create a new SMS or MMS campaign as a draft.
* [update\_sms\_campaign](#update_sms_campaign): Replace the full definition of a draft or inactive SMS or MMS campaign.
* [delete\_sms\_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.
### Warning
The returned link is publicly accessible without authentication and stays valid for a limited time. 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. To reuse a saved filter, fetch it with `search_customer_filters`, then copy its `filters` and `formula` values into the payload.
### Warning
The API doesn't resolve a saved filter referenced as `{"id": "..."}`. The unknown key is dropped and the campaign goes to every customer.
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.
### Warning
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:
* `sender.name` is required.
* `sender.sender` is required, and 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.
### Warning
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. |