Documentation

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 reads so on accounts without a loyalty program. 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 and tags go through update_contact afterwards. Manage residence/location in the authenticated theMarketer web app.

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, 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 the contact's own earlier choice, 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, in two steps: 1. Preview: pass contact_ids, a tag or a segment_id (several combine with AND) and no confirm_token. Nothing changes; the result gives matched, a sample, warnings, an ask_user question and a confirm_token. Ask the user the ask_user question in full, even when they already named every channel, and wait for their answer. 2. Confirm: call again with the same selection, channels=["email", "sms", "push", "loyalty"] and the preview's confirm_token. Only a preview gives one, so even when the user says they already saw the numbers, preview first. If the selection has changed since the preview, nothing changes and you are told to preview again.

Parameters

Returns

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 in two steps: 1. Preview: pass contact_ids, a tag or a segment_id (several combine with AND) and no confirm_token. Nothing is deleted; the result gives matched, a sample, warnings, an ask_user question and a confirm_token. Ask the user the ask_user question in full and wait for their answer. 2. Confirm: call again with the same selection and the preview's confirm_token. Only a preview gives one, so even when the user says they already saw the numbers, preview first. If the selection has changed since the preview, nothing is deleted and you are told to preview again. theMarketer then deletes the contacts in the background, so the result says the job was accepted, not that every record is already gone.

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

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. 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 fields present in the batch, replaces the contact's tags and custom columns with the batch's, resets its consent to the batch's and restores a contact removed with delete_contact. Tags apply to the whole import. 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 import runs in the background. status completed means the counts are in report; processing means the contacts were still being written when this tool stopped waiting, and list_contacts will show them; awaiting_approval means the file was parked for manual approval and nothing was imported yet.

Parameters

Returns

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

Use to audit automation triggers: who entered which automation, and when. Use get_contact_details to look at one of the contacts, and get_report with scope="automation" for how the automation performed.

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. 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 the audience's segments, or fetch one custom segment with its rules.

Use when the user asks which segments exist, how large one is, or what rules define it, 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 with total, pages and has_more; the note names the next page, and search narrows the list by name before paging. Passing segment_id returns that one custom segment with its rules and ignores page. Counts come from the last background evaluation, not from now: -1 means the count was not computed in this listing (every built-in System segment shows -1), which is not zero. System segments have ids starting with system-, have no rules and cannot be used as list_contacts.segment_id; custom segments (24-hex ids) can.

Parameters

Returns

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

Use when the user wants a reusable, named group of contacts defined by conditions: to target a campaign, to watch a cohort, or to filter list_contacts by segment_id. Not for a one-off count or list: list_contacts with filters answers that without creating anything. Call list_segments first to reuse a segment that already exists.

Each rule names a condition, an operator (omit it where the condition has a single one) and a value; some conditions add unit, campaign_id or max_value. Which conditions this domain can use, their operators and what each value must be come from get_audience_options(kind="segment_conditions"); the values one condition accepts (tags, segments, brands, categories, products, stores, custom-attribute values) from get_audience_options(kind="segment_values", condition=..., search=...). Names are accepted wherever theMarketer shows a picker and are resolved to ids; an unknown or ambiguous name is answered with the closest matches, so a segment never silently matches nobody. 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"]}.

The result says whether a segment was created or an identical one already existed (then nothing is written unless allow_duplicate=true) and lists the rules as stored. Evaluation is asynchronous: the count in list_segments stays 0 until the first run, and membership keeps updating unless lock is set. With match="all" every rule must hold; with match="any" one rule is enough.

Parameters

Returns

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 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.

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 and the open, click and conversion rates in percent, resend and A/B parts included. Rows come 20 per page by send date descending, drafts without a date last. 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 update_campaign 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 (long lines wrapped at 200 characters) with content_total_chars, pages and a note naming the next page; the other sections ignore page.

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 and for each part with data (main, resend, A/B variants, winner), the currency, the last open and click times and survey results; 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 when the user wants a new email campaign. With draft=true (default) the campaign is fully configured and left as a draft: nothing is sent until someone schedules it in the theMarketer app. 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 with no cancel once scheduled (update_campaign can still move send_at or change the content while it is scheduled). 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. 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. Omit sender_email and sender_name for the domain's default sender; a given sender_email must be one of the verified senders (get_campaign_details lists them). Omit segments for the whole email audience, or pass names or keys as list_segments shows them.

send_at is ISO 8601 at least 15 minutes ahead: with a UTC offset it is used as given, without one it is read in the shop's timezone. Omit it to send as soon as possible. The result carries the campaign id, its status, the effective UTC send time, the sender and audience as stored and a recipient estimate per segment. When the account is blocked from sending, the campaign stays a draft and sending_block says why. Follow it with list_campaigns or get_campaign_details, and use get_campaign_report once it was sent.

Parameters

Returns

Change an email campaign that is still a draft or scheduled: subject, sender, content, audience, send time or UTM tags, one or several at once.

Use when the user wants to edit a campaign before it goes out, or to move a scheduled send. Pass campaign_id (from create_campaign or list_campaigns) and only the fields to change; everything else is kept. It works on draft and scheduled campaigns: a campaign that is sending or paused is controlled with pause_campaign and resume_campaign, and a sent one cannot change. A scheduled campaign is scheduled again with the new values, which is also how a scheduled send is moved; there is no cancel, and send_now=true sends as soon as possible instead.

Content follows the campaign's mode: html for an HTML campaign, plain_text for a plaintext one, and it must still carry the unsubscribe link ({{unsubscribe_link}} as an <a> href in HTML, anywhere in plain text). sender_email must be one of the domain's verified senders. segments, exclude_segments and extra_recipients replace the stored lists; an empty segments list sends to the whole email audience. send_at is ISO 8601 at least 15 minutes ahead, read in the shop's timezone when it has no offset. The result lists the fields that were applied, the status, the effective UTC send time and the audience as stored. Test the result with send_test_campaign and follow it with get_campaign_details.

Parameters

Returns

Send a test copy of an email campaign to up to five addresses.

Use when the user wants to see the email in an inbox before scheduling it or after editing it. It sends one real email per address from the campaign as currently saved, with a '[Test]' subject prefix and test versions of the unsubscribe and tracking links; unsubscribed and unknown addresses receive it too. The campaign can be in any status, draft included; find the id with list_campaigns. Not for real recipients: use create_campaign or update_campaign to schedule the send.

Each domain may send 30 test emails per hour; once the limit is reached 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

Pause an email campaign that is sending right now.

Use when the user wants to stop a send in progress: status 'running', shown as 'Sending now' in list_campaigns. Batches already in flight finish, no further batch starts, and pending A/B or resend parts are paused with it; resume_campaign continues the send later. A scheduled campaign is not sending yet and cannot be paused or cancelled: use update_campaign to move its send_at. Drafts and sent campaigns have nothing to pause, and a campaign that is already paused comes back unchanged.

The result gives the status before and after the call and a note on what the pause means for the send.

Parameters

Returns

Resume a paused email campaign so the remaining batches go out.

Use when the user wants to continue a send that pause_campaign or the app's Pause button stopped: status 'paused' in list_campaigns. This is a real send to the rest of the audience, so confirm with the user first. The remaining batches are queued again and paused A/B or resend parts go back to pending. A scheduled campaign is not paused and goes out at its send_at (update_campaign moves it), a draft is scheduled with update_campaign, and a sent campaign has nothing to resume. A campaign that is already sending comes back unchanged.

The result gives the status before and after the call and a note on how the send continues.

Parameters

Returns

List the theMarketer domains (shops) this connection can work with.

Use first when the account manages several domains and you need to pick one: pass a domain's name or id as domain_id to any other tool. Single-domain accounts never need it.

Returns domains, one entry per domain with its id, hostname, shop URL and the user's role on it, plus count.

Parameters

No parameters.

Returns

Show the sending domain's setup: DNS records, senders and reply-to address.

Use when the user asks how their sending domain is configured, which DNS records theMarketer expects and which are still missing, or which sender addresses campaigns can go out from. It reads the current state and changes nothing; the DNS lookup runs live, so the call takes a few seconds. To re-run the full check and store its outcome use validate_domain; for whether the website tracking works use get_integration_health.

Returns the domain, valid, every expected record in dns_records with found, missing_records, the senders with the default_sender, sender_name, the effective reply_to, the extra and validated sender domains, a link to the settings page and a note naming the records to add when some are missing.

Parameters

Returns

Run the sending-domain check now: DNS records and email provider setup.

Use when the user asks whether their sending domain is set up correctly (SPF, DKIM, DMARC, sender identities), or has just added DNS records and wants them verified. The check runs now and takes about 10 seconds: it looks up every expected DNS record, asks the email providers to confirm the sender identities again and stores the outcome on the domain. For the full record list and the senders without re-running the check use get_sending_domain.

Returns valid true when everything passes. A failed check lists the records to fix in failed_records (name, type and the value to set) with a note on what to do next; an empty list with valid false means the records are in place and the providers have not confirmed the domain yet.

Parameters

Returns

Get the account's plan prices, billing date and usage totals.

Use for plan tier, pricing and email usage questions. Returns the plan tier (contact bounds, contacts counted, current and next monthly price), discount, sent, billing_date, email_credit and max_pause_months. Billing identity, invoices and payment details are not included; view invoices and payment settings in the authenticated theMarketer web app.

Parameters

Returns

Check that this connection can work with the domain.

Use when tools keep failing and you want to tell a connection problem from a data problem, or when the user asks whether the integration is set up. For the list of domains the connection can reach use list_domains; for whether the website tracking works use get_integration_health.

Returns valid true when the domain is reachable on an active paid plan. Free, paused or suspended accounts come back with valid false and a note explaining it, so a false here does not by itself mean the connection is wrong.

Parameters

Returns

Check whether the shop's website tracking reaches theMarketer.

Use when the user asks whether the tracking script is installed and working, before relying on funnel, audience or e-commerce figures, or when automations built on website events do not fire. It reads which standard events (page views, product views, add to cart, checkout, order...) and which custom events reached theMarketer in the last 48 hours; nothing is changed.

Returns tracking_active, the events and custom_events maps of event name to seen, the window_hours and a note on what to check when events are missing, e.g. no order event while products are viewed.

Parameters

Returns

Browse the shop's product catalogue with the filters, sorts and paging of the Products page.

Use when the user asks what the shop sells, which products are on sale, in stock, best selling, most viewed or best rated, or when picking products to feature in a campaign. Results come 15 per page with total, pages and has_more; the note names the next page.

Prices are in the account currency: price is what the shop charges now, full_price the regular price, and price_display / full_price_display render them the way the shop does. For an email block prefer availability="in_stock", skip products with disabled true or any issues, and use image and url as they come: click tracking and the campaign's UTM tags are added at send time. Products the merchant disabled in theMarketer are listed too and come back with disabled true.

category and brand accept a name or an id; get_product_options lists the ones this catalogue has. Use get_product_details for one product's description, reviews, history and orders.

Parameters

Returns

List the categories and brands of this shop's catalogue, with the ids the product filters accept.

Use before list_products when the user names a category or brand and you are not sure of its exact spelling, or when the user asks what categories or brands the shop has.

Without kind both lists come at once, 50 of each per page; with kind only that list, 200 per page. search narrows by name (case-insensitive, anywhere in the name or path) and falls back to the closest spellings when nothing matches literally. Category labels are full paths ("Root > Parent > Leaf"); list_products accepts the path, a unique leaf name or the id.

Parameters

Returns

Everything about one catalogue product, by section: summary, reviews, price and stock history, orders.

Use when the user asks about a specific product: its price and availability, what customers say about it, how its price or stock moved, or who bought it. Find the product with list_products first, or pass its shop id or SKU when exactly one product carries it.

By default returns summary (the product as list_products shows it, plus description, revenue and extra attributes) and reviews; ask for history and orders when the question needs them. Review ratings are on a 5-point scale, the summary's rating on 10. Reviews carry no reviewer names. Orders come newest first, 25 per page. Prices are in the account currency with price_display rendered the shop's way.

Parameters

Returns

Change what the product page lets a merchant edit: disable or enable a product, exclude it from recommendations, set its repurchase interval, or fill a custom column.

Use when the user wants a product hidden from campaigns and recommendations (or shown again), kept out of product recommendations only, given a repurchase interval in days for replenishment automations, or tagged in one of the catalogue's custom columns. Prices, stock, names, images and categories come from the product feed and cannot be edited here; the feed sync is where those change.

Pass at least one change. Each field is applied only when it differs from the product's current value, and changed lists what was actually changed. Custom columns are the ones the Products page shows beyond its standard fields (feed attributes such as colour or season, or columns the merchant added); a name that matches none is answered with the available ones. Find the product with list_products, or pass its shop id or SKU when exactly one product carries it.

Parameters

Returns

List the shop's orders for a period with their value, status, buyer, source and products, plus the order count, revenue and average order value of the whole selection.

Use when the user asks what was ordered recently, how many orders or how much revenue a period brought, which orders came from a campaign, automation or popup, what a given customer bought, or to look up one order by its number. Orders come 15 per page, newest first by default, with total, pages and has_more; the note names the next page. stats covers every order matching the filters, not just the page.

Each order carries the shop's order number, total, discount and shipping in the account currency (currency), the shop's status text, the date, the source that led to it and its product lines. contact_email is masked when the account anonymises contact data; pass contact_id to get_contact_details for the buyer's profile.

For the day-by-day, week-by-week or month-by-month split between orders attributed to theMarketer and the rest use get_order_trend; for the sent, clicks, conversion rate and revenue of each channel use get_ecommerce_stats.

Parameters

Returns

List the values the order filters accept: the statuses this shop's orders carry and the sources orders can come from.

Use before list_orders when the user names an order status and you are not sure how the shop spells it (each shop sends its own status texts, e.g. "Completed", "Finalizată", "processing"), or when the user asks which statuses or sources exist. The statuses come from the shop's own orders; the sources are the fixed set list_orders understands.

Without kind both lists come at once; with kind only that list. search narrows by text (case-insensitive, anywhere in the value) and falls back to the closest spellings when no status matches literally.

Parameters

Returns

Show how many orders and how much revenue the shop made per day, week or month, split between orders attributed to theMarketer and the rest.

Use when the user asks how sales are trending, how much of the shop's revenue theMarketer drives, or wants a chart-ready series of orders over the last two weeks, three and a half months or fifteen months. Each bucket has the orders and revenue that followed a theMarketer campaign, automation or popup (attributed_*) and every other order (other_*), in the account currency (currency); totals sums the buckets. Buckets end now and come oldest first: 15 days, 15 weeks or 15 months.

For the orders themselves, with buyer, status and products, use list_orders; for the sent, clicks, conversion rate and revenue of each channel use get_ecommerce_stats.

Parameters

Returns

List the account's discount codes as the Coupons page shows them, newest first.

Use when the user asks which coupons exist, which codes a customer can still use, whether a code was redeemed, or where a code came from. For "which codes can customer X still use" call with search=<their email> and used=false, then check expires_at: expired codes are listed too. To register a new code use save_coupon; for a customer's points and rewards use get_contact_details with the loyalty section.

Each coupon carries its code, value and type ('fixed', 'percentage' or 'shipping'), whether it was used, when it expires, its source ('API', 'popup', 'launcher', 'Campaign: <name>', 'Automation: <name>') and the contact it is assigned to (contact_email, masked when the account anonymises contact data, and contact_id for get_contact_details). Results come 15 per page with total, pages and has_more; the note names the next page.

Parameters

Returns

Register a discount code in theMarketer, optionally assigned to one contact.

Use when the user wants theMarketer to know a discount code, so campaigns can show it or a customer can receive it. The code itself is created in the shop; theMarketer only records it, and the same code can be registered more than once. Use list_coupons to see the codes already recorded.

Assigning the code to a contact records it on that contact and runs the reward-redeemed automation, so the customer may receive an email. An email that matches no contact leaves the coupon unassigned. Returns the confirmation with the code and the assignment.

Parameters

Returns

Report e-commerce performance per theMarketer channel over a period.

Use when the user asks how the shop performed through theMarketer, which channel brings the orders, or how much revenue campaigns and automations generated in a given month or window. The default is the last 30 days; pick a named period or give start and end for an exact window. It covers only what theMarketer sent and the orders that followed: for the shop's total order count and revenue, or the largest orders, use list_orders; for the attributed-vs-other trend use get_order_trend; for per-campaign figures use get_campaign_report; for who is on the site right now use get_realtime_visitors.

Returns one block per channel (newsletter, email_automation, sms_automation, push_automation, push, sms) plus total, each with sent, clicks, transactions, conversion_rate (transactions per 100 clicks) and revenue as numbers in currency. Archived campaigns are left out of the campaign channels. The period block echoes the window that was applied.

Parameters

Returns

Show who is on the website right now, from the last 5 minutes of tracking.

Use when the user asks how many people are on the site at the moment, where they came from, what they are looking at, or how many of today's visitors are known contacts. For past performance use get_ecommerce_stats, list_orders or get_campaign_report.

Returns visitors (last 5 minutes): total, from_marketer (visitors who arrived from a theMarketer campaign) with its percent, desktop and mobile counts with their percents, and sources with the percent of visitors from email, direct, social, other and search traffic. top_pages lists the 20 most viewed pages of the last 30 minutes with their view counts, and known_vs_anonymous gives the sessions per day over the last 8 days split into identified contacts and anonymous visitors. It does not list individual visitors. A section that could not be loaded reads {"unavailable": <reason>} while the others still answer.

Parameters

Returns

Add or remove loyalty points on a contact's balance, by hand.

Use when the user wants to award or deduct points outside the programme's own rules: a correction, a goodwill reward, a manual redemption. Confirm the amount with the user first: the balance changes immediately, and a decrease can take it below zero. To read a contact's balance, tier and points history first use get_contact_details with the loyalty and loyalty_history sections; to see who holds the most points use list_loyalty_members.

Returns the balance before and after the change, the tier before and after (null on a points programme) and a note when the balance went negative or the tier changed. When the new balance cannot be read back, points_after is null and note says the adjustment was applied, so do not repeat it. The adjustment appears in the contact's points history as a manual adjustment.

Parameters

Returns

Show how the account's loyalty programme is set up: type, tiers, earning rules, rewards and settings.

Use when the user asks whether the shop runs a loyalty programme, how contacts earn points, what the tiers are and how many points each needs, what points can be spent on, when points expire, or whether a points booster is running. For one contact's own balance and tier use get_contact_details with the loyalty section; for the members ranked by points use list_loyalty_members; to change a balance use adjust_loyalty_points.

Returns configured and type ('points' or 'tiers'), points_name, tiers with the points range of each (empty on a points programme), rules with what each pays and how often it has paid out, rewards contacts can redeem (empty on a tiers programme), the earning settings (when points are granted, taken back and expire, whether shipping counts, any pending delay) and the booster. Every section loads on its own: one that could not be loaded reads {"unavailable": <reason>} while the others still answer, and the note says when no programme is set up yet.

Parameters

Returns

List the loyalty programme's members ranked by points, optionally one tier or one name.

Use when the user asks for the top members by points, who is in a given tier, how many points a contact is about to lose, or who has redeemed the most. For everything about one member (balance, tier, points history, rewards) use get_contact_details with the loyalty sections; to change a balance use adjust_loyalty_points; for how the programme itself is set up use get_loyalty_program.

Each member carries contact_id, email (masked when the account anonymises contact data; pass contact_id to the other tools), name, points and tier (null on a points programme). Listing the whole programme also gives redeemed and about_to_expire (points expiring within 30 days); listing one tier gives reviews and referrals instead and orders by points only. The whole-programme list ranks every contact with an email address, so total is the audience size and contacts with 0 points come last. Results come 15 per page with total, pages and has_more; the note names the next page.

Parameters

Returns

Get one performance metric of a marketing channel, day by day.

Use when the user asks how email, SMS or push campaigns, automations or signup forms performed over a period: sends, opens, clicks, revenue, conversion, unsubscribes, form impressions and signups. The default window is the last 30 days; pick a named period or give start and end, and add compare_to for the change against the previous period or the previous year. Windows cover at most 90 days. For one campaign's full report use get_campaign_report; for orders and revenue per theMarketer channel use get_ecommerce_stats or list_orders; for how many contacts there are use get_audience_evolution (today) or get_audience_history (over time).

Returns series with a value per day, total over the window, by_campaign with the campaigns or automations behind it (largest first, 25 per page; campaigns_total, pages and has_more say how many there are and the note names the next page). With a comparison it adds previous_series, previous_total and change_percent. unit says whether the numbers are counts, percents or amounts in currency.

Parameters

Returns

Get the day-by-day history of an audience count: subscribers per channel or email list health.

Use for trends: how the number of email, SMS, push or loyalty subscribers, or the active, inactive, cleaned and bounced email counts, changed over time. The default window is the last 30 days; pick a named period or give start and end, and add compare_to for the change against the previous period or the previous year. Windows cover at most 90 days. For today's numbers and the last 7 days' joins and losses use get_audience_evolution; for list health today use get_audience_breakdown; for campaign performance use get_report.

Returns series with one value per day: the end-of-day snapshot of the count, not that day's signups, and latest, the last recorded day's count in the window. With a comparison it adds previous_series, previous_latest and change_percent. The note explains the values.

Parameters

Returns

List the reports saved in the Analytics section of theMarketer.

Use when the user asks which reports or dashboards they have set up, or before get_analytics_report when the report's name is not known. Both the reports theMarketer provides ('system') and the ones the account built ('custom') are listed. For one metric of one channel without a saved report use get_report.

Returns reports with each report's index, name, type and when it was created and last changed, 50 per page with count, pages and has_more. Several reports often share a name such as "Custom report": tell them apart by index and by when they were created or changed, and pass the index to get_analytics_report for the figures.

Parameters

Returns

Get one report saved in the Analytics section of theMarketer, over a period.

Use when the user asks for one of their saved reports or dashboards by name ("show me my Email overview report"), or for the figures the Analytics page shows for a period. The default window is the last 30 days compared with the previous period; pick a named period or give start and end, and set compare_to to change or drop the comparison. Windows cover at most 90 days. Use list_analytics_reports for the report names; for one metric of one channel without a saved report use get_report; for one campaign use get_campaign_report.

Returns the report's title and type, the window applied and widgets: each with its channel, scope, metrics (day-by-day series, total and change_percent, with a unit of count, percent or currency) and by_campaign with the campaigns behind the figures. links opens the report in theMarketer.

Parameters

Returns

Show how customers rate the shop: score, NPS split, rating trend, most reviewed products and most active reviewers.

Use when the user asks how the shop is rated, what its NPS is, whether ratings are improving, which products get the most reviews, who reviews the most, or how many reviews await moderation. For the reviews themselves use list_reviews; for one product's reviews and star distribution use get_product_details; to approve or reject a review use moderate_review.

Returns the score on the account's scale (score_as: '0-10', '0-5' or 'nps'), the nps and the average rating on both 0-10 and 0-5, reviews_total, reviews_last_30_days and pending_reviews, the promoters, passives and detractors with counts and percents, what the account collects ('products' or 'orders'), the rating trend over the last 8 periods, the 10 most_reviewed_products and the 10 top_reviewers (names and contact ids, no email addresses). Every section loads on its own: one that could not be loaded reads {"unavailable": <reason>} while the others still answer, and the note says when no review is approved yet.

Parameters

Returns

List customer reviews as the Feedback pages show them: newest first with ids and paging, or the 15 highest- or lowest-rated with product and contact.

Use when the user asks what customers wrote, which reviews await moderation, what the best or worst reviews say, or to find a review before approving, rejecting or deleting it with moderate_review. For the shop's score and NPS use get_reviews_overview; for one product's reviews use get_product_details.

The default, sort="newest", pages through the reviews 15 at a time, newest first, filtered by status and optionally by search; each row carries its review_id (for moderate_review), status, stars, text, date and the reviewer's name, without the product. sort="highest_rating" or "lowest_rating" shows the first 15 reviews ranked by rating with their product (shop id, name) and contact (contact id, name) and any photos, but no review ids; it takes no search or page. total, pages, has_more and the note say how to get the next page or the other view. Reviewer email addresses are never included.

Parameters

Returns

Approve, reject or delete one customer review, as the Feedback moderation page does.

Use when the user wants a pending review accepted (approve), declined or kept out of the product's rating (reject), or removed altogether (delete). Find the review and its id with list_reviews first; the ranked view carries no ids. Deleting is irreversible: confirm with the user before calling with action="delete".

Approving marks the review approved in the account: its rating counts in the product's rating and review count, the contact's NPS class is set from the rating and the loyalty programme may credit points to the contact's balance. Rejecting keeps the review on record as rejected and out of the product's rating; rejecting an approved review removes its rating from the product. Deleting removes the review from the account for good. Returns the review's status before and after, its stars and text, the product with its star distribution, and whether anything changed: a review that already has the requested status is left as it is.

Parameters