Aopy for Claude and ChatGPT

Planning context

Everything needed to plan the next sends in one call: what is scheduled in the next horizon_days (default 14) and the drafts, how the last 28 days went (open, click and unsubscribe rates, revenue, top 5 campaigns), which core automations are missing or paused, customer groups at risk, 7-day delivery health, emails left on the plan and upcoming Romanian/EU shopping dates. Days are in the account time zone (time_zone). Use it for "what should I send". suggestions_inputs are facts, not advice. Next: get_best_send_time, rank_segments, analyze_products, create_campaign_draft.

Account overview

A snapshot of the Aopy account: organization name, currency, time zone, language, plan and subscription status, usage against plan limits (contacts, emails this month and emails left, automations), sending domains and whether sending is paused, the email attribution windows, and connected stores with their sync status (at most 100). Call first in a new conversation: currency, time zone, language and attribution windows are facts you must not guess. Sections your role cannot read are listed in unavailable_sections. Next: get_planning_context.

No parameters.

List campaigns

Lists the organization's campaigns, newest activity first, with status, schedule, audience, open and click rates and revenue (cents plus a formatted string, in the organization's currency). Read-only. At most 100 per call (default 25); when has_more is true, pass next_cursor as cursor for the next page. A draft or scheduled campaign edited while you page moves to the top and can be missed; if campaigns were edited meanwhile, restart from the first page. For the results of one campaign call get_campaign_report; to rank or compare many campaigns call analyze_campaigns.

Get a campaign

Returns one campaign's settings (name, subject, sender, status, schedule), its audience (segment and lists), a readable summary of the email (visible text, links, product ids, images, whether an unsubscribe link is present) and, for an A/B test, its variants. An SMS campaign returns its text instead. Read-only; the raw HTML is never returned. Use it before editing with update_campaign_draft or before sending.

Get a campaign report

Returns delivery, engagement and revenue results for one campaign: sent, delivered, bounced and held back; open rates (Total includes automatic Apple Mail opens; Accurate when available, its state says why when not), click rate, revenue, orders, email ROAS, the 10 most-clicked links and, for an A/B test, each variant's results and the winner. Read-only. Money is cents plus a formatted string in the organization's currency. Event lists are capped at 20.

Analyze campaigns

Ranks, compares or explains campaigns in one call. mode rank: the top campaigns of a window by revenue, orders, open rate, click rate or date. mode compare: 2 to 20 campaigns side by side. mode periods: how open, click, conversion and bounce rates, orders and revenue changed between two periods. Returns rates (Total and Accurate open rates apart), revenue in the organization's currency, subject-line features, averages, best and worst. Read-only. Next: get_campaign_report for one campaign, get_deliverability_report when opens or bounces moved.

Get the best send time

Finds the hour of day when this organization's emails get the most clicks, from the last 90 days of email clicks in the organization's time zone (opens are not used), with the full 24-hour click histogram. Below 30 clicks it reports that it is still learning and names no hour. Read-only. Next: schedule_campaign at that hour.

No parameters.

Get the campaign building kit

Everything needed to build a branded email in Aopy: the Brand Kit colours, fonts and logo, the default sender, the email template list and every content block type with its fields and limits. Call it before create_campaign_draft, pick product ids with analyze_products or search_products, then pass blocks or template_id.

List segments

Lists the organization's saved segments with contact counts (stored counts, refreshed in the background, so they can lag; count_as_of says when each was taken, count_is_stale that it is old; count_is_estimated marks a count scaled from a sample). A segment not counted yet has contact_count null and count_pending true; ask again in a minute. Split parts carry split_of_segment_id. Up to 100 per page; use page to continue. To find the best segments use rank_segments; to see one segment's numbers and rules use get_segment_metrics. Read-only.

Get segment metrics

One segment's numbers and rules: member count, 30-day growth, average order value, lifetime and campaign revenue (money as cents plus formatted, in currency), days since last activity (not last order), open and click rates (0-1) and engagement; filter_json is the stored rule tree to edit with update_segment, filter_summary the same rules in words. null means no data yet. count_pending: still being calculated, ask again in a minute. metrics_capped: over 10,000 members, so contact metrics are null. filter_is_masked: emails and names in the rules are hidden for your role. Read-only.

Get segment fields

Lists every field a segment rule can use, with its operators, value shape, allowed values and limits, plus the tree grammar and a worked example. Call it before building a filter_json for preview_segment, create_segment or update_segment. Optional category narrows the list. Read-only; no data is read.

Preview a segment count

Counts how many contacts a rule tree matches without saving it. Give filter_json (build it with get_segment_fields) to count, or the job_id a previous call returned. status counted gives count and total_contacts; pending gives a job_id to check again in about 10 seconds (large audiences count in the background); invalid lists the problems to fix. Then save it with create_segment. Read-only.

Rank audiences

Ranks audiences in one call: RFM customer groups (Best customers, Regulars, At risk...) by store revenue, and saved segments and lists by the campaigns sent to them in the window: attributed revenue, click rate (fewer than 500 delivered ranks last as low_sample), size or 30-day growth. Use it for "which segments are best". Read-only. Next: get_segment_metrics for one segment, or create_campaign_draft with its segment_id.

Analyze the audience

Who the customers are, in one call: RFM groups (Best customers, Regulars, Slipping regulars, Gone...) with customers, orders, store revenue and the 30-day change, the biggest movements between groups, the RFM trend by band (daily over 90 days, weekly over 180 or 365), and email engagement buckets (high, medium, low, none, never emailed). Read-only, from daily rollups. Next: rank_segments to choose who to target, create_segment to save a group.

Search contacts

Searches the organization's contacts by name or email text, optionally narrowed to one list, segment or tag. Returns at most 50 per call, newest first, with a next_cursor for the following page. Emails and phone numbers are masked (for example a***@d***.ro); names, status, consent flags, order totals and up to 10 tags (tag_count: at least that many tags; the contact may have more) are returned. Read-only: it never changes a contact. Use get_contact for one profile.

Get a contact

Returns one contact's profile: name, status, consent, order totals, activity dates, up to 50 tags and lists, the RFM group (segment, recency, orders, revenue and average order in the organization's currency, churn risk 0-100, expected next order) and lifetime email engagement (sends, opens, clicks; opens include automatic ones by mail privacy features, so clicks are the stronger signal). The phone is always masked; the email is masked unless the connected user is an owner or admin. A block that could not be read is null with the reason in notes. Read-only.

List contact lists

Lists the organization's contact lists with member counts (a null count means it could not be read right now), the default list 'All' first, then by name. Returns at most limit lists (1-50, default 25) of page (default 1); when has_more is true, call again with next_page as page. 'All' contains every contact and cannot be added to. Use the list id with search_contacts or add_contacts_to_list. Read-only.

List tags

Lists the organization's contact tags by name (A to Z) with their contact counts. Returns at most limit tags (1-100, default 25); when has_more is true, pass next_cursor as cursor for the next page. Use a tag id with search_contacts to see who has it; create_tag makes a new one. Read-only.

List automations

Lists the organization's automations (email flows) with status, trigger, goal, lifetime enrollments, sends, clicks and attributed revenue. At most 100 per page (default 20); use page for more. Revenue is lifetime, as formatted text plus raw cents. With include_templates true it also lists Aopy's ready-made flows (welcome, abandoned cart, browse, post-purchase, win-back, ...) and which ones this organization already created; make a missing one with create_automation_from_template.

Automation statistics

Performance of one automation, chosen with automation_id (find it with list_automations; list_automations also gives each flow's lifetime totals): enrollments by state, emails sent, delivered, opened, clicked, bounced and unsubscribed with rates, and a per-step funnel (at most 100 steps). Contact details are not returned.

Revenue report

Store revenue for a date window (default last 30 days, at most 367): totals, average order value, email campaign and automation revenue, top campaigns and automations, and what each channel is credited. include adds attribution_models (both models per channel) and utm (per UTM source, medium or campaign), both 90 days at most, orders_by_status, and series (by day, week or month). Money is formatted text plus cents. Next: analyze_campaigns for campaign detail, analyze_products for products.

List orders

Lists the store's orders, newest first, one page at a time (at most 100 per page, default 25). Optionally filter by a date window (at most 367 days) or a search text. Buyer emails are masked. When more orders exist the result carries next_cursor: pass it back as cursor to get the next page. For totals and trends use get_revenue_report.

Analyze products

Best-selling products. basis store_sales (default): units and revenue per product from store orders, window at most 92 days within the last 4 months. basis units: units sold in the last 90 days (48 hours for today or yesterday; any other window is refused, use store_sales), with data_as_of and stale. basis ads: revenue credited to ad clicks with spend and ROAS, at most 20 products, only with an ad platform connected. A non-null product_id goes straight into a products block of create_campaign_draft; to find a product by name use search_products.

Search products

Finds catalogue products by name or SKU to put in a campaign: each product_id goes straight into a products block of create_campaign_draft. Sold-out products are listed with in_stock false unless in_stock_only is true. At most 25 per page and 4 pages; past that, refine the query. For best sellers use analyze_products.

Deliverability report

One read-only health check of email delivery: status against Aopy's thresholds for the window and the last 7 days, bounces and spam complaints, suppressions, mailbox providers, DKIM/SPF/DMARC per sending domain, account health checks, Gmail Postmaster numbers and whether sending is paused or slowed, with plain findings on what to fix. Use it when opens, bounces or spam complaints are a concern. Next: analyze_campaigns to find the campaign behind a spike.

Create a campaign draft

Creates an email campaign as a DRAFT; it never sends or schedules. Content is exactly one of: blocks (branded hero, text, buttons, images, live product cards), template_id (a ready-made template in its own design) or body_text (plain text). Aopy adds the unsubscribe link and legal footer itself. Call get_campaign_building_kit first for the brand, templates and blocks. Pass segment_id (list_segments) or list_ids (list_lists) for the audience, optionally narrowed by excluded_segment_ids or intersect_segment_id; without one it cannot be sent until update_campaign_draft sets it.

Update a campaign draft

Changes a campaign that is still a DRAFT: name, subject, preview text, sender name, reply-to, audience (segment_id or list_ids, excluded_segment_ids, intersect_segment_id) or its content. Content is one of blocks, template_id or body_text, as in create_campaign_draft, and replaces the whole body; Aopy adds the unsubscribe link and legal footer itself. Refuses a campaign that is scheduled, sending, paused, cancelled or sent. It never schedules or sends.

Send a test email to yourself

Sends one test copy of a campaign to the email address of the signed-in Aopy user who connected this assistant, and only that address; there is no way to choose another recipient. This is the only email the Create permission can send, and it goes only to you. Uses sample merge values and is rate limited. It does not send the campaign to the audience.

Set up an A/B test

Turns a DRAFT campaign into an A/B test of its subject, preview text, sender name or send time, with 2 to 5 variants. Each variant sets only the tested field; everything else comes from the campaign. A share of the audience (test_percentage) gets the variants; after duration_hours the winner by opens, clicks or revenue goes to the rest. Nothing is sent: then call send_campaign or schedule_campaign as usual. Calling it again replaces the variants. Results show in get_campaign_report once it is sent.

Create a segment

Creates a saved segment from a rule tree {version: 2, root: group}. Build the tree with get_segment_fields and check its size with preview_segment first. The count is calculated in the background (status evaluating); read it with get_segment_metrics. Fails if the name exists. It does not email anyone, change contacts or edit other segments.

Update a segment

Renames, re-describes or changes the rules of a saved segment. Read its current rules (filter_json) with get_segment_metrics, edit them, and send the whole new tree. When the rules change the new count is calculated in the background (status evaluating; read it with get_segment_metrics in a minute). A split part keeps its parent's rules: edit the parent instead. Built-in segments are refused, as in the app. New rules are refused while the segment (or a split part) starts an active automation or is the audience of a scheduled campaign, since that would email customers. It emails nobody.

Split a segment

Splits a saved segment into 2-20 equal random parts (for batch sends or tests). Each part is a new segment that follows the parent's rules; a contact stays in one part. Refuses a part of a part and a segment that is already split. Counts are calculated in the background; read them with list_segments or get_segment_metrics. It emails nobody: the parent keeps its members, and the parts are new segments no automation or campaign uses yet.

Create a tag

Creates a new contact tag. Fails if a tag with the same name exists (find it with list_tags instead). It does not apply the tag to any contact.

Add contacts to a list

Adds up to 500 specific contacts to a contact list. Contacts already in the list are skipped. It cannot add to the default 'All' list and does not remove anyone. It refuses a list that starts an active automation or is the audience of a scheduled campaign, since adding would email those contacts; it sends no email itself. Adding a whole audience (more than 500) is a background job in the app and is not available here; split the ids or use the Audience page. Check the new member count with list_lists.

Create an automation from a template

Creates an automation (welcome, abandoned cart, browse, post-purchase, win-back, ...) from Aopy's ready-made template as a DRAFT, with emails in the organization's language. Nothing is sent and nobody is enrolled until activate_automation. One per template: when one already exists (draft, active, paused, or archived and still counted) it is returned instead and nothing is created. Returns the draft's steps; the user can edit them in Aopy before turning it on.

Pause an automation

Pauses an active automation so it stops sending. Nobody is removed from the flow: people already in it are held and continue when it is turned on again with activate_automation. Pausing one that is already paused changes nothing.

Schedule a campaign

Schedules a DRAFT campaign to send at a chosen date and time. Goes through the same checks as the Aopy app (content, sending domain, consent, plan quota, abuse limits, canary), so it can refuse or hold the campaign; refusals are returned as written. With confirm false it only returns who the campaign goes to (the segment or lists) and the estimated recipient count, plus a preview_token, and changes nothing; a draft with no audience is not ready and says how to set one (update_campaign_draft). With confirm true the campaign is armed and will be emailed to real people at the chosen time; until then stop_campaign with action unschedule undoes it. Confirm true is refused without the preview_token from the confirm false call (valid 10 minutes, for this campaign, audience, date and time only). Time is in the organization's time zone unless time_zone is given.

Send a campaign

Sends a DRAFT campaign to its audience. Goes through the same checks as the Aopy Send button (content, sending domain, consent, plan quota, abuse limits, canary), so it can refuse or hold the campaign; refusals are returned as written. Like that button, it starts a 5 minute undo window: the campaign is queued to go out in about 5 minutes; until then stop_campaign with action unschedule undoes it. With confirm false it only returns who the campaign goes to (the segment or lists) and the estimated recipient count, plus a preview_token, and changes nothing; a draft with no audience is not ready and says how to set one (update_campaign_draft). With confirm true real people get the email; it is refused without the preview_token from the confirm false call (valid 10 minutes, for this campaign and audience only).

Stop a campaign

Stops a campaign without sending anything. action unschedule: a scheduled campaign goes back to a draft (this also undoes send_campaign during its 5 minute window). action pause: a campaign that is sending stops; resume_campaign continues it. action cancel: a sending or paused campaign stops for good and cannot be undone; call with confirm false first, show the user, then confirm true with the preview_token once they agree. Unschedule and pause act at once. An SMS campaign that is sending cannot be paused, only cancelled. Any other status is refused with the action to use instead.

Resume a paused campaign

Resumes a PAUSED campaign so the rest of its audience receives it: this emails real people. With confirm false it only returns the campaign, its audience and how many received it so far, plus a preview_token, and changes nothing; a campaign that is not paused, or was paused automatically for review, is not ready and says why. With confirm true sending restarts, under the same checks as the Aopy Resume button; it is refused without the preview_token from the confirm false call (valid 10 minutes, single use).

Turn on an automation

Turns on (or resumes) an automation so it emails real people as they trigger it. Call with confirm false first: it changes nothing and returns readiness, blockers, the new-contact safety gate and a preview_token. Show that to the user and only after they agree call again with confirm true and that token (valid 10 minutes, void if the automation is edited). Aopy's activation checks still apply; their refusals are returned as written. Stop it with pause_automation.

Delete a campaign draft

Deletes a campaign DRAFT that is no longer needed, with its A/B variants. Only a draft never sent, not scheduled and with nothing sent from it; anything else is refused. confirm false returns what would be deleted (name, created date, A/B variants, why it is deletable) and a preview_token, deleting nothing. Ask the user, and only after they agree call again with confirm true and that preview_token (valid 10 minutes, single use). Cannot be undone. A draft already gone answers already_deleted.

Delete a segment

Deletes a saved segment that is no longer needed; contacts are not deleted, only the segment. Refused for a built-in segment and while any campaign (any status, also as exclusion or intersect), automation, split part or ad audience uses it. confirm false returns what would be deleted (name, created date, why it is deletable) and a preview_token, deleting nothing. Ask the user, and only after they agree call again with confirm true and that preview_token (valid 10 minutes, single use). Cannot be undone. A segment already gone answers already_deleted.