Documentation

Upload an image into theMarketer's gallery and get a URL for campaigns and popups.

Use when the user wants a picture (a banner, a logo, a product shot) in a campaign or a popup and has it as a link or as a file. The image is stored in the account's newsletter file manager, in the folder My uploads / From MCP, and the returned URL goes into the image field of a popup or a campaign. Give exactly one source: image_url, a public https link the image is downloaded from, or image_base64, the file's bytes encoded in base64 (a data: URL prefix is fine). The gallery takes PNG, JPEG, GIF and WebP images of up to 2 MB; the format is read from the file itself, so the name or the link's extension does not matter.

The image stays in the gallery until it is deleted there in the app; deleting the From MCP folder removes every image in it, also from the campaigns and popups that show them. Uploading the same file twice stores two copies.

Parameters

Returns

List or count the contacts in the audience that match a set of filters.

Use when the user asks who is in the audience, how many contacts match some criteria, or when another tool needs a contact id. Filters combine with AND; run separate calls for alternatives. For a "how many" question set count_only=true and read total. For the headcount per channel and the last 7 days' joins and losses use get_audience_evolution instead, and get_contact_details for everything about one contact.

Results come 15 per page with total, pages and per_page; narrow the filters rather than paging through a large result. Bounds are inclusive: *_after includes the named day and *_before stops at the start of it, so a calendar month is created_after="2026-05-01", created_before="2026-06-01". Emails and phones come back masked when the account anonymises contacts. list_segments gives the segment_id values.

For geographic audiences, select an existing segment with list_segments and pass its segment_id; do not supply raw personal locations.

Parameters

Returns

Everything about one contact, by section: profile, purchases, loyalty, activity and deliverability.

Use when the user asks about a specific person: who they are, what they buy, their loyalty standing, what they did recently, or why an email did not reach them. Find people with list_contacts first; change what this tool shows with update_contact or unsubscribe_contact. By default it returns profile, rfm, ecommerce and loyalty; ask for other sections only when the question needs them, because each one is a separate lookup and "all" fetches every section.

A section that could not be loaded reads {"unavailable": <reason>} while the rest still answer; loyalty and loyalty_history read so on accounts without a loyalty programme. Long lists come one page at a time, newest first: orders (25 per page), the onsite and offsite activity timelines, the profile's consent_history and the delivery_log (30 each). One page walks them all together, so ask for page 2 only with the section you need. onsite holds the newest 100 events. Emails and phone numbers come back masked when the account anonymises contacts.

Parameters

Returns

Add one new contact to the audience by email address.

Use when the user wants a single person added, after a call, an event or a manual sign-up. Creates only: an address that already exists fails and points at update_contact, and the existing contact is left untouched. For more than a handful of contacts use import_contacts. Only name, phone and the three consents can be set here; birthday, tags and custom fields go through update_contact afterwards. Manage residence/location in the authenticated theMarketer web app.

The phone is saved in international form: +40722123456, 0040 722 123 456 and, on a domain whose store profile country is Romania, 0722 123 456 all become +40722123456. Letters, or fewer than 7 or more than 15 digits with the country code, stop the call with the fix to make.

The contact is saved quietly: no automations fire and no double opt-in email is sent, so the consent given here is final. Loyalty consent applies on plans that include the loyalty program. Only email consent is on by default; turn SMS or loyalty on only when the user asked for them, because a subscription implied from a conversation is not a ticked box.

Parameters

Returns

Change an existing contact's details, tags or channel consent.

Use when the user wants to correct or complete a contact's record: name, email, phone, gender, birthday, a custom field, the set of tags, or a subscription change including re-subscribing. Pass only what should change; every field you omit keeps its value. For an opt-out alone prefer unsubscribe_contact; for a contact that does not exist yet use create_contact. Manage residence/location in the authenticated theMarketer web app; this tool preserves existing location fields.

tags replaces the whole set: to add one, pass the current tags plus the new one (get_contact_details shows them). Tag changes fire the account's tag automations. Consent changes are logged as manual changes and can re-subscribe someone, so confirm intent first. The result carries the contact as it is after the change, updated the groups written (details the contact already has are not written again, and note says when nothing changed), and warnings names anything that could not be applied, such as an email or phone edit on an account that anonymises contacts.

Parameters

Returns

Opt one contact or many out of marketing channels, keeping the records.

First know which channels the user means. If they did not say, ask them before calling: every channel, or only some of email, SMS, push, loyalty? Use when the user explicitly wants contacts to stop receiving email, SMS, push or loyalty communication; confirm intent first, because this changes consent. Use delete_contact to remove the records themselves, and update_contact to re-subscribe.

One contact, chosen channels: pass email or contact_id, and channels. Only the requested channels change; existing opt-outs stay as they are. Channels the contact cannot use, such as SMS without a phone, come back in skipped. A channel in already_unsubscribed was already off before this call, opted out earlier or never opted in, not this call's doing: re-subscribing it is a separate, deliberate action through update_contact, never a repair of this result. To take many contacts off one channel only (for example SMS but not email), call this once per contact.

Many contacts at once, always every channel: pass contact_ids, a tag or a segment_id (several combine with AND). The first call answers needs_user_input with the one question to ask the user, even when they already named every channel: how many contacts match, what they lose and the first of them to check. Call again with the same selection, channels=["email", "sms", "push", "loyalty"] (as resume_arguments says), decision_token and decision_answers once they agreed. Nothing changes before that, and if the selection has changed meanwhile the question is asked again with the new count. A bulk unsubscribe replaces each contact's earlier choices with these four opt-outs, so an earlier opt-out from mobile push is cleared.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Delete one contact, or many at once: records are hidden and suppressed, not erased.

Use when the user wants contacts gone and never contacted again; confirm intent first, because the records cannot be restored from here. To keep a record but stop marketing to it use unsubscribe_contact; to see what it holds first use get_contact_details.

One contact: pass email or contact_id; it is deleted at once.

Many contacts: pass contact_ids, a tag or a segment_id (several combine with AND). The first call answers needs_user_input with the one question to ask the user: how many contacts match, what the delete does to them and the first of them to check; call again with the same selection, decision_token and decision_answers once they agreed. Nothing is deleted before that, and if the selection has changed meanwhile the question is asked again with the new count. theMarketer then deletes the contacts in the background; the tool checks a few of them after a short wait, and deleted is false with a note when they were still listed or could not be read back, so check again with list_contacts a few minutes later.

The contacts are opted out of every channel, their names are reduced to initials, their other personal fields are cleared and the records are hidden from the audience. Email addresses and phone numbers stay on file so the addresses remain suppressed, so this is not erasure: when the user asks for personal data to be erased, say plainly that this tool suppresses the records and keeps the email and phone. The account owner's own contact cannot be deleted.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Add or refresh many contacts at once, as the import wizard does.

Use when the user has a list of contacts to add, from a spreadsheet, another tool or the conversation, and there are more than a handful; for a single contact use create_contact, which never overwrites. Every row needs an email or a phone, and every email must be a valid address. Send at most 1000 rows per call, and keep rows with an email and phone-only rows in separate calls; a phone-only batch creates SMS-only contacts.

Location fields are not accepted here; manage them in the authenticated theMarketer web app.

New contacts are imported without double opt-in, so a subscribed batch is live at once: confirm the user has permission. With update_existing=true, a row matching an existing contact overwrites the standard fields that row fills and keeps the ones it leaves out, replaces the contact's custom columns with the ones the row names (a row without custom clears them), resets its consent to the batch's and restores a contact removed with delete_contact. To do that, rows that fill different fields are sent as separate imports, at most 10 per call, each listed in imports. Tags apply to the whole call; without tags, updated contacts keep the tags they have. Sign-up automations fire; tag automations do not. Custom column labels must already exist in the account: unknown ones come back in columns_ignored. Addresses on placeholder domains such as example.com count as blacklisted, so test with real-looking domains.

The imports run in the background. status completed means the counts are in report; processing means contacts were still being written when this tool stopped waiting, and list_contacts will show them; awaiting_approval means a file was parked for manual approval and its rows were not imported yet; incomplete means the call stopped after some imports had started: never send the whole batch again, only the rows in rows_not_sent.

Parameters

Returns

List the contacts who entered an automation on a given day.

Use to audit automation triggers: who entered which automation on a day. Use get_contact_details to look at one of the contacts, and get_automation_report for how many contacts an automation counted as entered: its entered is the settled count, while this list may also include contacts queued to enter.

Each entry is one contact entering one automation, ordered by entry time, with the contact's email, campaign_segment (the automation's name), barcode, mobile_install and subscribed_push; repeats of the same contact and automation name within a page are left out (rows of a deleted automation, which have no name, are all kept). Some days have no entry list, and note then says to use get_automation_report. No total is reported for this listing: has_more is true when the page came back full, so request the next page while it is true; the last page may turn out empty.

Parameters

Returns

Look up the values this domain uses (tags, countries, counties, cities, custom fields) and the conditions and values create_segment accepts here.

Use before list_contacts (its tag and custom_field filters), update_contact (its tags) or create_segment (its tag, country, county, city and custom:<label> conditions) whenever the exact spelling of a tag, country, county, city or custom field matters: filters and rules match values as stored, so a filter on "vip" finds nothing when the tag is "VIP Clienti". Countries are the codes stored on the contacts (usually ISO codes such as RO), not the ISO reference list. Before create_segment on an unfamiliar domain, call kind="segment_conditions", then kind="segment_values" with condition. Not for a parameter's fixed choices (channels, genders, statuses): those are in each tool's schema.

Without kind everything comes at once: tags, countries and custom fields in full, cities and counties 50 per page (one page walks both; see cities_total and counties_total), and the RFM groups with the name the tools accept, the label and the code. With kind only that list comes back, narrowed by search, 200 values per page with total, pages and has_more. kind="segment_conditions" reads the domain's live catalogue, 50 per page: only the conditions its plan allows plus its custom attributes (custom:<label>), each with its operators, what the value must be and a preview of the domain's values; unavailable names the conditions this domain cannot use and why. kind="segment_values" returns the domain's list for a condition, the fixed words of a choice condition, or, for products, categories and custom attributes (searched, not listed), the hits for search, required there; a condition that takes free text, a number or a window returns no values and a note saying what to pass.

Parameters

Returns

List segments by name, inspect custom rules or get a recipient estimate.

Use when the user asks which segments exist, how large one is, or what rules define a custom segment, and before create_segment, to reuse a segment that already exists. To see who is in a custom segment, use list_contacts with its segment_id.

The listing comes 50 segments per page, newest first (built-in segments last), with total, pages and has_more; the note names the next page, and search narrows the list by name before paging. Names longer than 200 characters are shortened in the listing and end in …; segment_id returns the full name. Set include_rules=true to inspect custom criteria. Review all rules and how they combine before suggesting a segment; names alone do not establish a match.

Passing segment_id returns one custom or system segment and includes stored custom rules. It ignores page. Set include_count=true to get its email recipients_estimate before campaign exclusions and smart sending. Count lookup requires segment_id; it never counts an entire listing. The separate count values come from the last background evaluation, not from now: -1 means the count was not computed in this listing, which is not zero. System segments have ids starting with system-; their rules are not exposed by this tool. A rule_count of 0 for a system segment does not mean an unrestricted audience. System ids cannot be used as list_contacts.segment_id; custom segments (24-hex ids) can.

Parameters

Returns

Create a custom segment from rules; theMarketer evaluates membership in the background.

Use when the user requests an independent segment. For a campaign needing a new segment, pass new_segment to campaign_wizard instead. Never create one for a one-off count or list; use list_contacts with filters. Check list_segments for an existing match. The first call writes nothing and asks for confirmation; return segment_operation, decision_token and decision_answers.create_segment='create' after the user confirms. Name and rules may be omitted on resume.

Rules take a condition, an operator (omit when only one exists) and a value; some also take unit, campaign_id or max_value. Discover conditions and operators with get_audience_options(kind="segment_conditions"), and values with get_audience_options(kind="segment_values", condition=..., search=...). Names resolve to ids; ambiguous or unknown values return suggestions. Examples: {"condition":"tag","operator":"is","value":"VIP"}; {"condition":"shopper_status","operator":"did_not_buy_in_last","value":6,"unit":"months"}; {"condition":"purchased_category","value":["Shoes > Men"]}.

An equivalent segment is reused unless allow_duplicate=true. The result lists the resolved rules. identity_pending means the id or creation result could not be verified: do not repeat creation. Evaluation is asynchronous; list_segments shows its last_processed and counts. Membership updates can trigger existing automations. lock freezes membership after evaluation. With match="all" every rule must hold; with match="any" one is enough.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Get the audience headcount per channel and the last 7 days' joins and losses.

Use when the user asks how many contacts they have on email, SMS, push or loyalty, or how many joined or left recently. Use get_audience_breakdown for list health (active, inactive, bounced, cleaned) rather than headcount, and get_audience_history for a day-by-day history over a custom date range.

For each channel, contacts is the current headcount (contacts with that channel's identifier who are not opted out of it), and joined_last_7_days and lost_last_7_days count subscriptions and unsubscriptions in a rolling 7-day window ending now. The loyalty headcount is 0 on plans without the loyalty program. A metric that could not be computed reads {"unavailable": <reason>} while the others still answer, and note names it.

Parameters

Returns

Get the health of the email list: engaged, dormant, bounced, blacklisted and cleaned contacts.

Use when the user asks how healthy or clean their list is, how many contacts are active versus inactive, or how many bounced, were blacklisted, were cleaned or unsubscribed from everything. These are deliverability counts, not headcounts: use get_audience_evolution for how many contacts each channel has, and list_contacts with engagement="active", "inactive" or "cleaned" to see who is in a bucket.

active_email and inactive_email split the reachable email contacts (address present, not opted out, not blacklisted, not cleaned) by whether they ever opened, clicked or were tracked on site. bounced are hard-bounced addresses opted out of email, manually_unsubscribed are contacts opted out of every channel, and blacklisted and cleaned are the addresses flagged by the blacklist and by the automatic list cleanup. A bucket that could not be computed reads {"unavailable": <reason>} while the others still answer.

Parameters

Returns

Analyze the customer base: RFM groups, purchase frequency and the on-site funnel.

Use for "how do my customers look" questions: how customers spread across RFM groups (champions, loyal, at risk, lost...), how many buy once versus repeatedly, and where visitors drop out between the homepage and an order. To see the contacts behind a number use list_contacts with rfm_group or funnel_stage; for headcounts use get_audience_evolution and for list health get_audience_breakdown.

These are the three analyses of the Audience pages RFM analysis, Frequency analysis and Funnels, read as the account computes them: RFM and frequency are refreshed at most every two hours over the analysis period configured in the account, and the funnel covers the last three months. This tool only reads them and never changes that period. An analysis that could not be loaded reads {"unavailable": <reason>} while the other two still answer.

Parameters

Returns

List the domain's signup popups (newsletter popups, wheel of fortune, scratch and win, choose a gift) with their status and how they did in a period.

Use when the user asks which popups exist, which are live, how a popup performs, or whenever you need a popup id for the other popup tools. For one popup's texts, fields, rewards and display rules use get_popup_details; the daily series for all popups together is in get_report.

Each row carries the id, name, status (draft, active, paused) with status_label, links.app_url to open it in the app, and stats for the chosen period: impressions, signups and the signup rate in percent. status=active lists the popups currently live on the shop. The list has no total: rows come 20 per page, newest first, and has_more says whether to ask for the next page (the note names it). The period changes the figures only, never which popups are listed. The row does not say which kind of popup it is, when it shows or when it was created or last saved; get_popup_details does.

Parameters

Returns

Everything configured on one signup popup: its kind (classic, wheel of fortune, scratch and win, choose a gift), layout and motion, status, the texts, form fields, rewards, colours, image, countdown and display rules, and whether it can go live.

Use when the user asks what a popup says or shows, before update_popup to see the current content and the reward ids to keep, before enable_popup to see the blockers, or to check why a popup is not showing. Find the id with list_popups. Figures for a period are on list_popups, not here.

The result carries the name, status with status_label (needs_attention when its status needs a look in the app or it was never fully set up), family, layout, motion, game, the template, ready_to_publish with the blockers enable_popup would report (missing discount codes, chances not adding up, a missing device, a tag switched on without a tag...), the stored counters as stats, created and updated times, links.app_url to open the builder, and content: the popup decoded into what update_popup takes, including each reward's id. The look of the template (fonts, sizes, effects) is not part of the result.

Parameters

Returns

Look up what a signup popup can be built from on this domain: the triggers and the words the display rules take, the form fields and the contact columns a custom field can save into, the tags, the gift pictures for a choose-a-gift popup, whether unique discount codes can be generated, and the industries and languages the template library is filtered by.

Use before create_popup or update_popup to pick a valid trigger, field kind, contact column, tag, country, category or gift picture, and whenever a value's exact spelling matters. Not for a popup's own content: that is in get_popup_details.

kind=triggers lists each trigger with its key, when it fires and the display_rules parameters it takes, plus rule_parameters, the ones every trigger takes. kind=rule_values needs field and lists that vocabulary as value and label: audiences, frequencies, page_kinds, traffic_sources, weekdays, countries (code and name) or categories (the full path, with its id in the value). kind=fields lists the field kinds with their parameters, the custom field among them. kind=columns lists the domain's contact columns a custom field can save into, by name. kind=tags, kind=gift_icons, kind=industries and kind=languages are plain value lists. kind=coupon_webhook says whether the shop's coupon connection is set up. Lists come 200 per page, narrowed by search.

Parameters

Returns

The library templates a signup popup can be created from: one family at a time (classic, wheel of fortune, scratch and win, choose a gift), optionally one layout, motion or industry, in the store's template language unless another is asked for.

Use before create_popup: the template fixes the popup's layout, motion and look for good (a different layout means a new popup), so show the user the preview pictures and pass the chosen template_id. For what a popup can then say and do, use get_popup_options; for the popups that already exist, list_popups.

Each row carries the template id, name, preview image URL, layout, motion, image position, game and industry, 20 per page. Templates come in the store's template language (Settings > Store profile); when the store has none, or no template of this family exists in it, the result is needs_user_input asking which language to use, with the languages that do have templates as options: ask the user, then call again with decision_token and decision_answers, or pass language directly.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Create a signup popup as a draft from a library template: a classic signup popup, a wheel of fortune, a scratch and win or a choose a gift, with its texts, form fields, rewards, colours, image, countdown and display rules.

Use when the user wants a new popup on the shop: pick the template with list_popup_templates first (show them the preview pictures), because the template fixes the popup's layout, motion and look for good; a different layout means a new popup. Every section besides template_id and name is optional: what is left out stays as the template has it, and a popup created from a template alone is valid. The popup is always created as a draft; enable_popup publishes it, update_popup changes it later. Names (tags, categories, countries, contact columns, gift pictures) are matched for you, and an unknown one is answered with the closest matches; get_popup_options lists them all.

Texts take plain text or simple HTML (bold, italic, underline, links, colours, line breaks); the shop shows anything else as plain text. In a game's success headline {{reward_label}} is replaced by the reward won. A game created without rewards carries the template's example rewards and codes, which must be replaced with update_popup before enabling it. The result carries the new popup_id, the content as stored, ready_to_publish with the blockers enable_popup would report, warnings for what was taken from the template, a name read loosely or text saved differently than sent, and links.app_url to open the builder.

Parameters

Returns

Change a signup popup's name, texts, form fields, rewards, colours, image, countdown, devices or display rules, or take a part off it; sections left out stay as they are.

Use when the user wants to edit an existing popup: new wording, other fields, real discount codes on a game, a different trigger or audience. Read it first with get_popup_details: fields, rewards and display_rules replace the whole list, so pass every item to keep together with the change, and keep each reward's id from the details so winners' codes stay attached to it; success, lose and colors change only the keys given. remove takes the countdown, image, tag, close link or success image off the popup. The layout, motion and look come from the template and cannot change here; a different layout means a new popup with create_popup. Not for publishing or pausing (enable_popup, pause_popup).

A draft or paused popup is saved directly. A popup that is live on the shop is saved only after the user confirms: the result is then needs_user_input with the one question and pending_changes listing what will change; ask the user, then call again with the same arguments plus decision_token and decision_answers. Once saved, the change shows to visitors on their next page load. Nothing is written while the question is pending or when the user cancels. Texts take plain text or simple HTML (bold, italic, underline, links, colours, line breaks), and in a game's success headline {{reward_label}} is replaced by the reward won. The result lists what was applied (changed), the content as stored, ready_to_publish with the blockers enable_popup would report, and warnings for a name read loosely or text saved differently than sent.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Publish a draft or paused signup popup on the shop, after the user confirms: from the next page load visitors see it.

Use when the user wants a popup live, or back after a pause. Before anything changes the popup is checked the way the app's Enable button expects it: set up from a template, rewards complete for a game (real discount codes, chances adding up to 100, a gift picture per gift, the shop's coupon connection for unique codes), at least one device, a tag when tagging is on, and the shop able to render it; everything that stops it is reported at once and nothing is enabled (get_popup_details shows the same blockers without trying). A popup that is already active is reported as such. To stop it later, pause_popup; to edit it while it is live, update_popup.

The first call answers needs_user_input with one question, the trigger and the audience the popup will show to: ask the user, then call again with decision_token and decision_answers. Once enabled the result gives the status before and after, whether the shop's popup feed already lists it, warnings (another active popup on the same trigger, which visitors see one at a time; the first active popup of a domain can take up to 5 minutes to appear) and links.app_url.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Take a live signup popup off the shop: visitors stop seeing it on their next page load, and everything about it is kept.

Use when the user wants a popup to stop showing for a while, before deleting it (delete_popup takes only popups that are not live), or to edit it without visitors seeing the steps. Pausing changes nothing else: the texts, rewards, rules and figures stay, and enable_popup brings it back as it was. Only an active popup can be paused: a draft was never enabled, so there is nothing to pause; a paused one is reported as such. No confirmation is asked, as the app pauses in one click and the step is reversible.

The result gives the status before and after, with links.app_url to open the popup in the app.

Parameters

Returns

Delete a draft or paused signup popup for good, after the user confirms.

Use when the user wants a popup gone: an abandoned draft, a test, a popup that was replaced. Only a popup that is not live can be deleted, as in the app: an active one needs pause_popup first. The popup disappears from list_popups and cannot be restored from here (duplicate_popup beforehand keeps a copy); its statistics stay in the reports (get_report channel=forms). To stop a popup without losing it, pause_popup is enough.

The first call answers needs_user_input with the one question to ask the user; call again with decision_token and decision_answers once they agreed. Nothing is deleted before that.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Copy a signup popup as a new popup that is not live, on the same domain or on another domain of the account.

Use when the user wants a variant without touching the original, a backup before a big edit, or the same popup on another of their shops. The copy has the same template, texts, fields, rewards and display rules; statistics are not copied. On the same domain the copy keeps the original's status unless that is live, in which case the copy is paused at once, so no second popup starts showing; the copy is named name or "Copy of <original>". On another domain (target_domain_id) the copy is created as a draft from the same template and filled with the original's content; rewards get fresh ids, and a tag, custom field column or category that does not exist there is left out and listed in warnings. A copy to another domain is made only after the user confirms: the first call answers needs_user_input with the question, and the next call carries decision_token and decision_answers. Not for publishing the copy (enable_popup does that) or for changing it (update_popup).

The result carries the copy's id, name, domain, status and links.app_url; calls about a copy on another domain pass that domain as domain_id.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

List the account's automated journeys (automations) with their status, trigger, objective and headline results, newest first.

Use when the user asks which automations exist, which are running or paused, how a journey is doing, or whenever you need an automation id for the other automation tools. For one journey's steps and content use get_automation_details; for its per-step and per-contact figures use get_automation_report.

Each row carries the id, name, status (draft, running, paused) with status_label, the objective, the trigger key and its editor label, created and updated times, currency and stats for the chosen period: contacts entered, waiting in the journey (in_progress), completed, messages sent with unique opens and clicks (summed over the channels), transactions, revenue and its growth against the previous period, and under channels each channel's own sent, unique opens and clicks, their rates in percent, transactions, conversion rate and revenue; only channels with activity are listed, so a channel absent from channels sent nothing in the period. Rows come 20 per page; theMarketer reports no total, so has_more is true when the page came back full and the note names the next page. The period changes the figures only, never which journeys are listed; start_date and end_date give the calendar days it covered.

Parameters

Returns

Everything configured on one automated journey: its trigger with settings, the steps in flow order with their ids, which email steps have a saved body, and on request the HTML of one email step.

Use when the user asks what an automation does or how it is set up, before update_automation to see the current trigger and steps (the flow is in the exact shape those tools take, ids included), or to read an email's copy. Whether a journey is ready to start is not decided here: start_automation with dry_run=true runs every start check and never starts it, and its real call asks the user before anything starts. Find the id with list_automations. Performance figures are in get_automation_report.

The result carries name, status with status_label, objective, created and updated times, links.app_url to open the editor, and flow: the trigger (type, run mode, entry window in the shop's timezone, trigger-specific fields) and nested steps - email, sms, push, mobile_push, delay, filter (with yes / no branches), split (a / b), add_tags, remove_tags, unsubscribe, start_automation, webhook - plus orphans not connected to the trigger and notes (what could not be read back exactly, a filter condition that checks a message step which is not in this journey, and a start_automation step whose journey was deleted). A step the tools do not edit reads as type 'kept' with a summary. Email steps in flow carry has_content, not their body; the body is read with email_step_id. email_steps lists each email step with its subject, branch, has_content and the blocks its body holds. With email_step_id the saved HTML of that step comes as email_content, 80 lines per page (a line longer than 200 characters is cut only where a line break changes nothing) with pages and a note naming the next page; each block in it shows as its placeholder and its options come in email_content.blocks, so the lines joined with newlines and the blocks can be passed back to update_automation as they are, unless notes name a block the tools cannot write back in that email. Without it the body is not fetched.

Parameters

Returns

Show one email step of an automation as a contact would receive it: placeholders filled in, products taken from the shop's catalogue, links resolved.

Use after create_automation or update_automation saved an email body, and before start_automation, to see the real result and whether anything is still wrong; get_automation_details shows the saved source instead. The email is rendered for a sample contact (the signed-in user's address) with real products from the catalogue, and nothing is sent. rendered carries the HTML 80 lines per page (a line longer than 200 characters cut only where a line break changes nothing) with pages and a note naming the next page. check says whether the email is fit to send: placeholders left unfilled, product slots that stayed empty, a missing unsubscribe link, and a note on what to fix; it covers the whole email whatever page is shown. Its warnings name each filtered product block that too few products in stock meet, with at most how many do (the remaining places are filled with the newest products in stock), each one with a price no product of the catalogue reaches, and each one whose filters the rendering cannot confirm otherwise, such as a price some products may meet; a block that enough products meet needs no warning. A products-from-the-trigger block is warned only for a price no product of the catalogue reaches, since its filters apply only when the event that started the journey carries no products.

The step must be an email step of this journey with a saved body; without one the call says so and names update_automation. Products come from the shop's catalogue rather than from one contact's cart or orders, so a block fed by the trigger shows catalogue products here and the contact's own once the journey runs. When the email has a countdown block, previewing also prepares its countdown images.

Parameters

Returns

How one automated journey performed over a period: contacts entered and completed, sends, opens, clicks, orders and revenue per channel and per step, and on request who a message step reached.

Use when the user asks how an automation is doing, which step loses contacts, how a specific email or SMS in the journey performs, or who received it. Find the id with list_automations, whose rows already carry headline figures; come here for the breakdown. For the journey's setup use get_automation_details.

The result carries totals (entered, completed, waiting inside the journey right now, about_to_enter), channels (email, sms, push, mobile_push with counters and rates in percent) and steps: one entry per step in flow order with its id, kind, a readable label, the branch it sits in and its counters (entered, exited, yes/no for filters, sends, opens, clicks, orders, revenue and rates for message steps; 0 where no contact reached the step in the period, which the note then says). With step_id the recipients of that message step come 25 per page with email or phone, opened, clicked, orders and revenue; theMarketer reports no total, so has_more means the page came back full. Dates are whole days in Romanian time (Europe/Bucharest).

Parameters

Returns

Look up what this domain can build automated journeys from: the triggers, filter conditions and step kinds its plan allows (with the fields each takes), the objectives, the email senders, and the domain's own value lists (tags, segments, products, categories, brands, campaigns, order statuses, forms, surveys, custom events, attributes, loyalty tiers, email providers, locations, journeys that can be started by another journey).

Use before create_automation or update_automation to pick a valid trigger key, condition key, step type or sender, and whenever a value's exact spelling matters (a tag, a segment, an order status). Not for a journey's own steps: those are in get_automation_details.

kind=triggers lists each trigger with its key, category, when it fires and needs_tracking (it fires on website activity reported by the theMarketer tracking script); with search (e.g. the trigger key) each one found also carries its fields (required first, with the values_field to look values up) and the general settings it offers. kind=conditions lists each filter condition with operators, what value must be, fixed choices, what an operator or choice word stands for when the word alone does not say it (operator_meanings, choice_meanings), the values_field for list values, and applies_to when it only works after certain triggers; the domain's contact attributes (custom:<Label>) and product attributes (product_attribute:<Label>) are included. kind=actions lists the step kinds with their fields and consequences. Triggers, conditions and actions show only what the domain can use; the unavailable lines say which groups need a plan or feature it lacks. kind=objectives and kind=senders are short lists. kind=email_blocks lists the blocks an automation email can hold (products filled in for each contact) with their options, the personalisation placeholders and the rules for placing blocks in the HTML, and the account's brand (logo, social links, contact e-mail, colours, whether it saved a footer, whether Aqurate recommendations are connected, the language its emails are set to) for HTML that matches it; the blocks' default texts follow that language, so write the email's own text in it too. With trigger, it says whether that trigger's event carries products. kind=discount_templates lists the designs a Discount block can show, 20 per page, in the account's language, narrowed by industry, event and tags, with the values those filters take; the filters combine, so a design shows only when it matches all of them. Each design is a picture behind its preview_url link, which you cannot see: give the user the links and wait for their pick before writing the block; choose one yourself only when the user left the choice to you. kind=values needs field and returns id and label pairs, 200 per page, narrowed by search; products are searched (search required), categories and campaigns are searched when search is given and listed otherwise.

Parameters

Returns

The journeys an automation can be created from without describing every step: theMarketer's pre-built library by category, the popular picks for this account, and the account's own saved journeys.

Use when the user wants a ready-made automation (welcome series, cart recovery, win-back, birthday...) or asks what templates exist; then pass the chosen template_id or saved_flow_id to create_automation, which sets it up as a draft to review in get_automation_details. For a journey built step by step, use get_automation_options instead.

source=library returns groups by category, each card with its template_id, name, description, objective, impact and the card's copy (what the journey will do, who enters, what you need); only categories and cards this account's plan offers are listed, and a card names its trigger when the same journey is among the popular picks. source=popular returns up to four library journeys whose trigger no running journey of the account uses yet, each with its trigger named. source=saved returns the account's saved journeys with their trigger and step count, 50 per page. search narrows the library and the popular picks by name or description, and the saved journeys by name (they have no description).

Parameters

Returns

Create a marketing automation (a journey) as a draft, from a trigger and steps, from a pre-built template, or from a saved journey.

Use when the user wants a new automated flow: a welcome series, a cart-recovery sequence, a post-purchase follow-up, a birthday message. Pass exactly one source. (1) trigger plus steps: the trigger says what starts the journey (get_automation_options kind=triggers lists the keys; searched by key it shows the fields one takes) and steps is the ordered list of what happens next; a filter step branches into yes/no, a split into a/b, and on create each branch has its own steps (repeat a step in both branches when both should do it): joining the branches into one shared filter or delay step is done afterwards with update_automation, with a kept step marked shared=true where the other branch reaches it. Names (tags, segments, products, categories, campaigns, forms) are resolved for you and an unknown name is answered with the closest matches. (2) template_id from list_automation_templates: the pre-built journey is copied with its emails. (3) saved_flow_id from list_automation_templates source=saved: one of the account's own saved journeys is copied under new step ids, email bodies included. Not for editing an existing journey (update_automation) or for sending a one-off message (campaign_wizard).

Every email step you write needs html: the full email body with an <a> whose href is exactly {{unsubscribe_link}}. Products that theMarketer fills for each contact go in as blocks: an empty <div data-block="<slot>"></div> in the HTML and an entry in the step's blocks (get_automation_options kind=email_blocks lists them). On save each slot is renamed to the block's id: each email step written comes back in flow.steps with its blocks under their new slots, which later updates use, and a render_check of the email rendered for a sample contact. Some steps have consequences worth telling the user: a webhook step sends contact data to the given URL and stores its credentials with the journey, an unsubscribe step cannot be undone from the journey, SMS steps spend SMS credit, and a start_automation step sends contacts into another journey. SMS and push text is plain text (product blocks go in email steps), a split needs at least one step in one of its branches, a filter condition takes one value unless it is one of the list conditions, and no path from the trigger runs through more than 50 steps. The result is always a draft with the stored flow and the id of every step; start_automation makes it live.

When a draft with exactly this name was created in the last 10 minutes, the call answers needs_user_input first: use that draft or create another. If a call fails without an answer, check list_automations for the draft before creating it again.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Change an automation's name, trigger or steps; the steps given replace the whole flow.

Use when the user wants to rename a journey, change what starts it, or edit its steps: add a message, change a delay, rewrite an email, adjust a condition. Read the current flow with get_automation_details first: every step there carries an id, and a step passed back with its id is kept, with its statistics and its saved email body; passed back exactly as it reads, it is stored as it is, names and all. A step without an id is new; a step left out of steps is removed. An email step with an id and no html keeps the body it has; html given replaces it; a new email step needs html with an <a> whose href is exactly {{unsubscribe_link}}. Products theMarketer fills for each contact go in as blocks: an empty <div data-block="<slot>"></div> in the HTML and an entry in the step's blocks (get_automation_options kind=email_blocks lists them). On save each new slot is renamed to the block's id, as the result's blocks show; later updates use those slots. On an email step with an id, pass only blocks (with the ids get_automation_details gives as slots) to change blocks' options: list only the blocks to change; the others keep their saved options. Give each block's slot, type and the options to change, and the options left out keep their saved values; the rest of the saved body stays exactly as it is, even when it was made in the web app's email editor. Pass html too to change the email's text or layout, or to swap a block for one of another type: a block listed with its saved slot and type still keeps the options left out; a new slot of the same type as one saved block the HTML no longer holds, with no option set differently, takes over that block and its saved options; any other new slot starts from the defaults. The HTML (its lines joined with newlines) and blocks get_automation_details gives for a step can be passed back as they are, unless its notes name a block the tools cannot write back. Every email step comes back in flow.steps with its blocks and body: written, with a render_check of the email rendered for a sample contact, or kept when its saved body stayed as it was. Steps shown as type kept are passed back as they came; a kept filter or split passed back without branch_1 or branch_2 keeps the saved steps there, and [] removes them. Not for starting, pausing or deleting (use start_automation, pause_automation, delete_automation) and not for creating one (create_automation).

A draft or paused journey takes any change. A running journey takes changes live, and contacts already in it continue on the new flow, except for changes that would leave them stranded: removing or retyping a delay or webhook step they may be waiting at, or changing the trigger type. Those need the journey paused first, which ends the journey for the contacts currently in it. The result lists what changed (empty, with nothing saved, when everything passed matches the journey as stored) and the flow as stored, with the id of every step. No path from the trigger may run through more than 50 steps.

A nested edit works the same way: pass the whole flow back and change only the step in question. To make the delay inside a filter's yes branch 2 days, with the flow read as steps=[email a1b2c3d4e5, filter f6g7h8i9j0 whose yes branch is [delay k1l2m3n4o5 of 1 day, sms p6q7r8s9t0] and whose no branch is empty], send steps=[{"type": "email", "id": "a1b2c3d4e5", "subject": ..., "preview_text": ...}, {"type": "filter", "id": "f6g7h8i9j0", "conditions": [... as read ...], "yes": [{"type": "delay", "id": "k1l2m3n4o5", "amount": 2, "unit": "days"}, {"type": "sms", "id": "p6q7r8s9t0", "text": ...}], "no": []}]: every other step is passed back as read with its id, so it is kept, and only the delay changes.

Parameters

Returns

Start a draft or paused automation after the user confirms what will happen, or check whether it could start.

A call without dry_run never starts anything by itself: it returns the user's question first, and the journey starts only once they answer Start, so call it when the user wants the journey live. dry_run=true only checks and says what a start would do.

Use when the user wants a journey live: from then on every contact the trigger matches enters it and gets real emails, SMS or push messages. Call with dry_run=true first to see what would stop the start, and what a start would do, without starting it. Only a draft or a paused journey can be started; a running one is left as it is, and pause_automation stops it. Before starting, the journey is checked: it needs a trigger with at least one step connected to it, every email step needs a saved body that renders fit to send (as preview_automation_email shows it; a rendering that cannot be read just then does not stop the start, the note says so) and a sender address the domain has verified (a step without one of its own sends from the domain's default sender, so the domain needs one), push steps need web push (mobile push steps the mobile app push) set up on the domain, SMS steps need SMS credit or an SMS provider, the trigger and every filter condition must be ones the domain's plan includes (a loyalty trigger also needs the loyalty program), a filter condition on a message step must check a step of this journey, and a start_automation step must point at a journey of this domain that starts with automation_triggered and does not start this one back (directly or a few journeys on); anything missing is reported and nothing starts. Starting a paused journey does not bring back the contacts who were in it when it was paused.

A journey that passes the checks is not started on the first call: it answers needs_user_input with one question for the user that says what will happen: the journey and domain, who enters, how many emails, SMS and push notifications a contact receives and over how long, that SMS uses credit (with the credit left), every email that creates a unique discount code as it sends (its value and how long it is valid), the journeys it sends contacts on into, the contact details each webhook step sends and to which URL, the channels each unsubscribe step unsubscribes contacts from (which the journey cannot undo), and for a paused journey that the contacts it had do not come back. Call again with decision_token and decision_answers once they agreed; nothing starts before that. A journey edited since the question (its steps or an email body) is not started, and the question is asked again.

The result gives the status before and after, and the note says when a journey this one starts is not running yet, or when the trigger fires on website activity (needs_tracking) and no website events have arrived lately, so no contact would enter yet. With dry_run the same checks run, nothing is asked and nothing changes: ready says whether the journey could start now, problems what stops it (each with its fix; a journey that is already running, or a domain whose plan does not include automations, is reported there too), not_checked what could not be checked this time and consequences what a start would do, in the words of the question a start asks.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Pause a running automation after the user confirms, ending the journey for the contacts in it.

Use when the user wants a journey to stop sending: before editing a delay or the trigger, before deleting it, or to switch it off for a while. Only a running journey can be paused; a draft or a paused one is reported as such. Pausing is not a gentle stop: contacts currently in the journey (waiting for a delay or a next step) leave it for good, and starting it again later does not bring them back; new contacts stop entering until start_automation runs it again.

The first call answers needs_user_input with the one question to ask the user, which says how many contacts are in the journey now; call again with decision_token and decision_answers once they agreed. Nothing is paused before that. The count may have moved on by then and the pause still applies; a journey that was edited, stopped or started again since the question is not paused, and the question is asked again.

The result gives the status before and after.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Delete a draft or paused automation for good, with its reports, after the user confirms.

Use when the user wants a journey gone: an abandoned draft, a test, a flow that was replaced. Only a draft or a paused journey can be deleted; a running one needs pause_automation first, which ends the journey for the contacts in it. Deleting removes the journey from the automations list for good, with its reports; it cannot be restored from here (duplicate_automation beforehand keeps a copy). To stop a journey without losing it, pause_automation is enough.

The first call answers needs_user_input with the one question to ask the user, which names the journey, its status, how many contacts ever entered it and the journeys whose start_automation step sends contacts into it; call again with decision_token and decision_answers once they agreed. Nothing is deleted before that. A journey that was edited, started or stopped since the question is not deleted, and the question is asked again.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

Copy an automation as a new draft, in the same domain or into another domain of the account.

Use when the user wants a variant of a journey without touching the original, a backup before a big edit, or the same journey on another of their shops. The copy is a draft with the same trigger, steps and email bodies, under new step ids, and keeps the original's name unless name is given; statistics are not copied. The original needs at least one saved step; a brand-new empty draft has nothing to copy. Same-domain copies are immediate and the result carries the new id. A copy into another domain (target_domain, one where the user is admin or owner) is queued by theMarketer: the tool waits a few seconds for it and reports created with its id, or queued when it has not appeared yet, in which case list_automations on that domain shows it shortly. A copy on another domain keeps the email senders and the start_automation targets of the original, which belong to this domain: review them there before starting it. Not for moving contacts between journeys or for starting the copy (start_automation does that).

Parameters

Returns

Send a test copy of one email step of an automation to up to five addresses.

Use when the user wants to see an automation email in an inbox before starting the journey or after changing the step. It sends one real email per address from the step as currently saved: its subject, preview text and body. When an address belongs to a contact of the domain, the email is personalised with that contact's own data (name, cart, orders); any other address gets sample data. Find the automation with list_automations and the step id with get_automation_details; the step must be an email step whose subject and body are already saved (update_automation saves both). Not for real recipients: the journey itself reaches them once start_automation runs it.

Each domain may send 30 test emails per hour across its automations; once the allowance is used up the remaining addresses come back as 'throttled' and nothing is sent to them. 'sent' means the message was accepted for delivery; delivery problems are not reported back, so ask the recipient to check the inbox and spam folder.

Parameters

Returns

Send the saved text of an automation's SMS step to the signed-in user's own phone, as a test, after the user confirms.

Use when the user wants to read an automation SMS on their own phone before starting the journey or after changing the step. The test always goes to the phone number on the signed-in user's theMarketer profile, never to a number given here, and it sends the step's text exactly as saved (update_automation changes it). It is charged like a real SMS: one message of SMS credit at the account's price, unless the domain sends through its own SMS provider. Find the automation with list_automations and the step id with get_automation_details.

The first call answers needs_user_input with the one question to ask the user: it carries the text, the masked number and what the test costs, so ask it in full. Call again with the same automation_id and step_id plus decision_token and decision_answers once they agreed; nothing is sent before that. If the text or the phone number changed since the question was asked, nothing is sent and the question comes back for the new text. Once handed to the SMS provider (delivery itself is not confirmed), the result reports the text, the masked phone, cost_per_sms_eur and the remaining_credit_eur left after the test.

theMarketer sends one test SMS per domain every 10 seconds; a test that comes too soon after the previous one is not sent and the result says to try again in a few seconds. A test needs the price of one SMS in whole euros of credit; when the credit is below that the tool says so before asking anything, and get_transactional_credits shows the balance. When only this domain's own credit can be read, the question shows it even when low, since a credit the account shares across its domains may cover the test; if it does not, the test is not sent and the result says so.

Parameters

Returns

The operation's result, pending user questions, or cancellation.

List the account's campaigns on every channel, with status, audience, schedule and headline results, most recently scheduled first.

Use when the user asks which campaigns exist, what was sent or is scheduled, or how recent campaigns did, and whenever you need a campaign id for the other campaign tools. For the latest sent campaign call with status="sent" and read the first row. It lists SMS and push campaigns too; the other campaign tools cover email only.

Names are not unique. If several campaigns match the user's request, show their ids, subjects, statuses and dates and ask which one they mean before changing anything. Never select one by guesswork. A draft's send_at is only the time saved on it, even in the past, and schedules nothing; it is null while no send time is set yet: that is chosen when the campaign is scheduled with schedule_campaign.

Each row carries the id, name, status with status_label as the app shows it, type, mode, subject, sender, audience (segment names, exclusions, extra recipients, smart sending), send_at, sent_at, recipients and stats: lifetime sent, delivered, unique opens and clicks, transactions, revenue, unsubscribes, the unique open rate (contacts who opened / delivered) and the click, unique click and conversion rates in percent, resend and A/B parts included. A campaign with an automatic resend also carries resend_after, resend_status and resend_send_at (an estimate until the campaign has finished sending); a manual resend made with create_campaign_resend gives the id of the campaign it follows up in source_campaign_id and its name in source_name. Rows come 20 per page by send date descending; a draft with no send time set sorts by when it was created. A draft that never reached the wizard's schedule step, such as a new manual resend, is listed after every other draft, often many pages in: look it up with search by its name instead of paging. The listing reports no total: has_more is true when the page came back full and the note names the next page. Archived campaigns appear only with status="archived". For the breakdown per part, links, timeline and contacts use get_campaign_report.

Parameters

Returns

Everything configured on one email campaign, by section: what it says, who gets it, when, how links are tagged, and the rendered email.

Use when the user asks what a campaign contains or how it is set up, before campaign_wizard with campaign_id to see the current values, or before create_campaign to learn the domain's verified senders and defaults (summary.domain_defaults). Find the id with list_campaigns. Email campaigns only; performance numbers are in get_campaign_report.

By default it returns summary, audience, schedule and tracking; content renders the email and is heavier, so ask for it only when the user wants to see the copy or check the HTML. The rendered content comes 80 lines per page (a line longer than 200 characters is cut only where a line break changes nothing) with content_total_chars, pages and a note naming the next page; the other sections ignore page.

summary.resend describes the automatic resend (who gets it, after how many hours, its subject, preview and send time) and is null when there is none. Its send time is an estimate until the campaign has finished sending (send_at_is_estimate). A campaign made with create_campaign_resend carries summary.manual_resend instead: the sent campaign it follows up, its rule and who it reaches, counted at send time from that campaign's recipients.

Parameters

Returns

How one email campaign performed: counters and rates, benchmark, clicked links, daily timeline and the contacts behind each metric.

Use when the user asks how a campaign did, what was clicked, who opened or bought, or how it compares with the account's usual results. Find the id with list_campaigns; its rows already carry the headline stats, come here for more. Email campaigns only.

By default it returns overview only; each extra section is a separate read, so ask for what the question needs. overview gives counters and rates for the whole campaign (all), for the campaign without its automatic resend (all_without_resend, the headline the theMarketer app shows) and for each part with data (main, resend, A/B variants, winner), the currency, the last open and click times and survey results. The totals add the parts up without matching people, so a contact who got the main email and the resend counts twice; quote all_without_resend for the campaign itself and resend for the follow-up. For the share of recipients who opened quote unique_open_rate; unique_click_rate is the share of those openers who clicked, not of all recipients. open_rate counts every open, and on all_without_resend it is opens per 100 messages sent, so above 100 means more opens than messages sent. A manual resend made with create_campaign_resend is a campaign of its own: its results are under its own id, not in the resend part of the campaign it follows up. A resend shows 0 sent when no contact matched its rule at send time; get_campaign_details shows whether it went out.

benchmark sets the rates next to the account's and the industry's averages; links lists the top clicked links, the most engaged contacts and the products ordered; timeline gives seven daily rows of opens, clicks, orders and revenue plus clicks by country, in a window anchored on today for campaigns older than six days; contacts lists who did what for one metric, 50 per page, narrowed by search. Contact rows carry the contact id and name, never the email address. Links, timeline and contacts exist only once the campaign has been sent: for a draft or scheduled campaign they are skipped with a note, while overview still answers with zeros. A section that could not be loaded reads {"unavailable": <reason>} while the rest still answer. Rates are percentages.

Parameters

Returns

Create an email campaign through theMarketer's wizard - sender, audience, subject, content, schedule, tracking - and schedule it or leave it as a draft.

Use only outside a conversation, when a program already holds every decision (audience, send time, A/B test, resend) as data. When a user is talking, even if they said everything in one message, use campaign_wizard and give what they said as the answers to its first round; their words are answers, not arguments. With draft=true (default) the campaign is fully configured and left as a draft: nothing is sent until it is scheduled with schedule_campaign. Pass draft=false only when the user explicitly asked to send or schedule and has confirmed content, sender, audience and time: that is a real send; once scheduled, update_campaign can move it or change its content, and delete_campaign cancels it. When in doubt keep the draft and call send_test_campaign first. Email campaigns only.

Content is either html or plain_text, never both, and must carry the unsubscribe link: an <a> whose href is exactly {{unsubscribe_link}} in HTML, the placeholder anywhere in plain text. Do not put HTML comments (<!-- ... -->) in the html. For product blocks use table-based layout and inline CSS, absolute URLs and plain product links: click tracking and the campaign's UTM tags are added at send time; take names, prices (price_display) and images from list_products.

The audience is the user's decision. Pass segments only with segments the user named (names or keys as list_segments shows them); an empty list sends to the whole email audience, only when the user asked for everyone. When they did not say who should receive it, omit segments; when they only described it ('loyal customers', 'inactive for 6 months'), pass that description as audience_description and no segments: the result offers exact name matches or a choice between existing and new segments. Ask only for missing criteria: pass the specific question in audience_clarification to return audience_criteria. Omit it when the user already gave the period, such as 'last 30 days'. Use list_segments to find suitable segments, then let the user choose. Names do not establish matching rules. Without a description, the result asks whether to use all subscribers, an existing or a new segment. Either way the first call creates nothing until the user confirms the audience and its recipient count. Never pick a segment or call create_segment on your own. Pass a typed answer as the user wrote it: a segment name selects that segment, any other text comes back as their audience criteria. Choosing another audience opens a follow-up question; ask what they want, then retry with the new audience and the other original arguments, without the previous decision_token or decision_answers.