Documentation

Add (or update) a subscriber in the audience by email.

Use when the user wants to add a contact/subscriber to their list. By default the import is queued; pass sync=true to process immediately and get the result in the response. birthday is YYYY-MM-DD.

Add a subscriber identified by phone number (no email).

Use for SMS-only contacts. The phone number must be valid for the account's country prefix.

Add multiple subscribers in one call.

Use for bulk imports (e.g. a list of contacts). Each entry needs at least an email.

Get a subscriber's profile and subscription status by email.

Use when the user asks whether someone is subscribed, or for details about a specific contact.

List subscribed or unsubscribed email contacts, optionally in a date range.

Use when the user wants the actual list of contacts (not counts; for counts use get_subscribers_evolution). Large results are truncated with a summary.

Add and/or remove tags on a subscriber.

Use to label contacts for segmentation (e.g. "vip", "newsletter"). add_tags must contain at least one tag (the API requires it); pass overwrite_existing=true to replace all existing tags.

Get the current audience size per channel and the last-7-day changes.

Use when the user asks how many subscribers/contacts they have (email, SMS, push, loyalty) or how many joined/left recently. Returns, per channel: contacts (current headcount), subscribed_contacts_in_last_7days, unsubscribed_contacts_in_last_7days. For a day-by-day history over a custom date range use get_audience_report.

List subscribers who entered an automation on a given day.

Use to audit automation triggers (who entered which automation and when). Paginated: per_page max 100.

Get the unique referral link for a subscriber.

Use when the user wants the refer-a-friend URL for a specific contact. Returns null if the email is not a subscriber.

Unsubscribe a contact from marketing channels.

Use when the user explicitly wants to unsubscribe someone. Without channels, the contact is unsubscribed from all channels. This affects consent and is hard to undo — confirm intent first.

Delete a subscriber record entirely (by email and/or phone).

Use only when the user explicitly wants the contact removed from the platform, not just unsubscribed. At least one of email/phone is required. This cannot be undone — confirm intent first.

Anonymize a subscriber's personal data (GDPR erasure).

Use for data-protection requests ("forget this customer"). This permanently removes personal data and cannot be undone — confirm intent first.

List the account's campaigns, newest first.

Use when the user asks what campaigns exist/were sent. Filter by name (search), channel (type) or sent-after date (start_date, YYYY-MM-DD). Paginated: limit max 100.

Create and schedule a campaign for the whole audience.

Use when the user wants to send/schedule an email, SMS, or push campaign. send_at is "YYYY-MM-DD HH:MM"; html is the full message content (max 500KB). The campaign goes to all subscribers (audience_type=all). This schedules a real send — confirm the content and time with the user first.

Get the detailed performance report of one email campaign.

Use when the user asks how a specific campaign performed (opens, clicks, revenue). Get the id from list_campaigns.

Get the most recently sent campaign (or the last few with limit, max 10).

Use when the user asks about their latest campaign.

List the theMarketer domains this connection can operate on.

Use first when the account may manage multiple domains (shops) and you need to pick one: refer to a domain by its `name` (or `domain_id`) in the `domain_id` parameter of any other tool. Single-domain accounts never need this.

No parameters.

Set the catalog feed URL (product, category, or brand feed).

Use when the user wants theMarketer to import the catalog from a feed.

Set the orders feed URL for importing historical orders.

Use when the user wants theMarketer to sync orders from a feed.

Fire a custom event for a subscriber (triggers automations).

Use when the user wants to trigger automation flows tied to a custom event name. The platform prefixes the name with "__sm__" automatically.

Validate the account's email sending DNS setup (SPF/DKIM/DMARC).

Use when the user asks whether their sending domain is configured correctly or has deliverability problems.

Get the account's billing details and usage costs.

Use when the user asks what they are paying / their plan usage.

Get the remaining SMS credit for the account.

Use before SMS sends or when the user asks about SMS balance.

Verify that the connector's theMarketer credentials are valid.

Use to debug the connector setup; returns true when the credentials work.

Record an order in theMarketer (triggers automations, revenue stats).

Use when the user wants to sync/register a sale. Requires number, firstname, lastname, at least one product, and email_address or phone. Pass retail=true (with the store_* fields) for in-store/POS orders. Processing is queued; a true result means the order was accepted.

Update the status of an existing order (e.g. shipped, delivered, returned).

Use when the user wants to change an order's fulfillment status. Processing is queued; a true result means the update was accepted.

Get ecommerce statistics for the last 30 days (orders, revenue, conversion).

Use when the user asks how the shop performed recently. The period is fixed by the API to the last 30 days.

Get the real-time visitor metrics for the website.

Use when the user asks who/how many people are on the site right now.

Create or update a product in the catalog.

Use to sync product data. mode="create" requires name, url, main_image, category, brand, price, sale_price (<= price), availability (0-2), stock and created_at ("YYYY-MM-DD HH:MM"); mode="update" needs only id plus the fields to change.

Create or update a product category.

Use to sync the catalog's category tree. hierarchy is the full path (e.g. "Home > Furniture > Chairs").

Create or update a product brand.

Use to sync the catalog's brand list.

List the unused coupons available to a subscriber.

Use when the user asks what discount codes a contact can still use.

Register a discount coupon, optionally assigned to one subscriber.

Use when the user wants to create/import a discount code so theMarketer can distribute it in campaigns. expiration_date is a date like YYYY-MM-DD; type is fixed (amount), percentage, or shipping (free shipping).

Get a subscriber's loyalty program status (points, tier, rewards).

Use when the user asks about a contact's loyalty points or level.

Increase or decrease a subscriber's loyalty points.

Use when the user wants to award or deduct points (e.g. a manual correction or a reward). This changes the customer's balance — confirm the amount first.

Get one performance metric for a marketing channel over a date range.

Use when the user asks how email/SMS/push campaigns, automations, or signup forms performed (sends, opens, clicks, revenue, conversion, unsubscribes, form impressions...). For audience size and growth use get_subscribers_evolution or get_audience_report instead. Scope per channel: email/sms/push accept "campaigns" or "automation"; forms accepts "popups" or "embedded". Metrics per channel: email -> sent, opens, unique-opens, open-rate, unique-open-rate, clicks, unique-clicks, click-rate, unique-click-rate, transactions, revenue, conversion-rate, average-order-value, unsubscribed, unsubscribe-rate, complaints, complaint-rate, bounced, bounce-rate; sms/push -> same minus opens/bounces/complaints; forms -> total-impressions, impressions, total-subscribed-users, subscribed-users, total-subscribe-rate, subscribe-rate. Pass previous_start_date/previous_end_date to compare with a previous period.

Get the day-by-day history of an audience metric over a date range.

Use for trends: how the number of subscribers (email, SMS, push, loyalty) or the list hygiene (active/inactive/cleaned/bounced emails) evolved over time. For the current headcount and the last-7-day signups/unsubscribes per channel use get_subscribers_evolution, which is always up to date. For campaign performance use get_report. total-* metrics are end-of-day snapshots of the headcount: each day's value is the total on that day, not new signups, and total_period is the latest snapshot in the range. The subscribed-* metrics are not supported by theMarketer's reports engine yet and return an error. Pass previous_start_date/previous_end_date to compare with a previous period.

Get the product reviews feed.

Use when the user wants to see collected product reviews. The API returns an XML string feed (not JSON).

Import a customer review for an order (and optionally its products).

Use to import existing reviews (e.g. from another platform). review_date is a date string like YYYY-MM-DD.

Add a product review on behalf of a customer (merchant import).

Use to attach a review to a product (by product id or SKU) for a given customer email; the contact is created as subscriber if missing.

Update the MerchantPro integration settings (feeds and credentials).

Use only for shops on the MerchantPro platform; pass just the fields to change. Returns per-field success/failed status.

Send one transactional email (order confirmation, password reset...).

Use for one-off operational emails, not marketing campaigns (use create_campaign for those). This sends a real email — confirm the content and recipient first. Pass queue=true to enqueue instead of sending synchronously. Attachments are base64, max 7MB each / 15MB total. The recipient address must have a resolvable DNS (MX) record.

Send up to 100 transactional emails in one batch.

Use for operational sends to multiple recipients. This sends real emails — confirm with the user first. Pass send_async=true to enqueue the batch.

Send one transactional SMS.

Use for operational SMS (order updates, codes). This sends a real SMS and consumes SMS credit — confirm with the user first. The recipient must start with + (international format) and have at least 10 digits after the country code.

Get the email delivery logs for one recipient.

Use to debug whether/when emails reached a contact (delivered, bounced...). Paginated: per_page max 100; optional start/end dates.

Register a mobile push token for a subscriber.

Use when integrating a mobile app: links the device token (type e.g. ios/android) to the subscriber so they can receive push notifications. Note: the API may take ~10s to respond.

Remove a subscriber's mobile push token.

Use when a device should stop receiving push notifications (logout, uninstall). The contact stops receiving mobile push on that platform.