apply_bulk_contact_action
ChatGPTApply a bulk contact change previewed with preview_bulk_contact_action, after the user approves it. Pass its confirmation_token, and repeat the previewed operation, affected_count and (for tag operations) tag_name so the user can see what they are approving; a mismatch with the preview is refused. The action applied is exactly the previewed one. Runs in the background (large lists take a few minutes).
cancel_scheduled_send
ChatGPTCancel a send that is scheduled for later and hasn't started. Sends already in progress can't be cancelled here.
create_audience
ChatGPTCreate a saved audience: an auto-updating segment of contacts defined by rules. Membership is computed in the background, so member_count is the preview count; the live count settles within a minute. Counts against the plan's audience limit. Audience names are unique per workspace.
create_automation
ChatGPTCreate an automation: one trigger plus ordered steps (waits, emails, tag changes). It is created PAUSED: nothing sends until set_automation_active turns it on. Each email step needs a subject and either content (a Tiptap body; see get_email_block_reference) or draft_id (an existing draft to copy). Call get_automation_reference first for valid triggers.
create_draft
ChatGPTCreate a new email draft on the workspace theme. Optionally pass the body as a full Tiptap content document (see get_email_block_reference), and the subject / preheader its sends will default to. Or pass template_id (from list_email_templates) to start from a designed gallery template. Note that a template brings its own theme. Returns the draft id and editor link.
create_field
ChatGPTCreate a custom contact field so contact data for it is kept (e.g. company, plan, signup_date). data_name must be lowercase snake_case and unique in the workspace. Types: string, number, boolean, datetime (ISO dates), phone (stored as E.164).
delete_contact
ChatGPTPermanently delete one contact and their history (engagement, tags, field data). This cannot be undone. To stop emailing someone, prefer unsubscribe_contact. Requires confirm: true.
duplicate_draft
ChatGPTCopy a draft (content, theme and tags) into a new draft named '<title> (Copy)' or title.
edit_draft_blocks
ChatGPTTargeted edits to a draft's body by blockId (from get_draft): replace a block, insert new blocks before/after a block or at the start/end, delete a block, or insert a premade component with its copy customized. Prefer this over replace_draft_content: untouched blocks, designs and collaborators' cursors are left alone. Applied live to the collaborative editor. All-or-nothing: if any operation can't apply, nothing changes and you get the errors.
get_audience
ChatGPTGet one audience: its rules (in reproducible form), member count and a link.
get_audience_rule_reference
ChatGPTEverything you need to write audience rules for this workspace: each contact field with its type, allowed operators and value format; the tag catalog; which behavior rule kinds are available (Shopify purchase/cart/view, total spend, per-email engagement) and the recent sends email_activity rules can target; and today's date for relative-date math. Inactivity ("hasn't been active in 30 days") is last_activity less_than the ISO date 30 days ago; recently active is within_last with a day count.
get_automation
ChatGPTOne automation's trigger and steps in order. Email steps include their subject, the text of the email, and the draft_id of the email. While the automation is paused, edit an email by editing that draft; reactivating snapshots the latest content.
get_automation_reference
ChatGPTWhat automations in this workspace can trigger on and do: the trigger types with the audiences, forms, custom events and (when connected) Stripe/Shopify events they can reference, the step types, and the rules (a wait of at least 5 minutes between emails is inserted automatically; automations are created paused).
get_contact
ChatGPTOne contact's full profile: status, tags, custom field values, engagement (delivered/opened/clicked and rates), and their recent email activity.
get_draft
ChatGPTRead a draft: title, subject, preheader, status and the LIVE body as Tiptap JSON, with a blockId on every block (use these ids with edit_draft_blocks), plus a plain-text rendering.
get_email_block_reference
ChatGPTThe complete reference for writing email bodies: every Tiptap block and inline node Audienceful can render (paragraphs, headings, lists, buttons, images, containers, columns, tables, product lists, social icons, merge tags…), their attrs and allowed children, layout and color attrs, the block-edit operation format, the design rules, and a worked example. Read it once before creating or editing an email.
get_import_status
ChatGPTProgress and results of an import started with import_contacts (or in the app).
get_send_report
ChatGPTFull report for one send: recipients, opens, clicks, CTOR, bounces (hard/soft), unsubscribes, complaints, top links and top countries.
get_theme
ChatGPTThe theme an email renders with: colors (with dark-mode twins), fonts, sizes, spacing, buttons, containers, header/footer layout. Theme fields are where an email's look belongs. Defaults to the workspace's default theme; pass draft_id for that draft's theme.
get_workspace_overview
ChatGPTOrient yourself in the connected Audienceful workspace. Call this first. Returns the workspace name and plan, subscriber counts by status, every audience (with member counts), custom contact fields (their data_names are what contact data, imports, merge tags and audience rules key on), the tag catalog, sending identities (from-addresses), and plan limits.
import_contacts
ChatGPTBulk-import contacts through Audienceful's import pipeline: invalid and disposable addresses are skipped, typos are fixed, addresses are verified, and existing contacts are updated in place. Provide EITHER contacts (JSON rows) OR csv + column_mapping. Up to 5000 rows per call. - Field values key on field data_names (list_fields). Unknown names are rejected; create them first with create_field. - tags are applied to every imported contact; per-row tags go in each row's tags. - Imports never re-subscribe contacts who unsubscribed and never trigger automations. - Runs in the background: poll get_import_status with the returned id.
list_audiences
ChatGPTList the workspace's audiences with member counts and their rules.
list_automations
ChatGPTThe workspace's automations with active state and membership counters.
list_components
ChatGPTPremade designed sections (hero, feature grid, testimonial, CTA block, header, footer…) plus the workspace's saved components. Each lists its numbered text slots. Insert one with an edit_draft_blocks insert_component op, passing text_overrides {slot: new text} to rewrite its copy while keeping the design.
list_custom_events
ChatGPTThe workspace's custom automation events (fired by the user's own app or trigger_custom_event).
list_drafts
ChatGPTList the workspace's email drafts, most recently edited first.
list_email_templates
ChatGPTThe designed template gallery (complete email designs, each with its own theme) for create_draft's template_id.
list_fields
ChatGPTList the workspace's contact fields. A field's data_name is the key used for contact data (upsert_contact.fields, import_contacts), for merge tags in emails ({"type":"mergeTag","attrs":{"data_name":"first_name"}}) and for audience rules. Data sent for a data_name with no field is silently dropped, so create the field first (create_field).
list_images
ChatGPTThe workspace's uploaded email images (newest first); their URLs can be used as image src.
list_imports
ChatGPTThe workspace's 20 most recent contact imports, newest first.
list_scheduled_sends
ChatGPTEmail sends that haven't finished yet: scheduled for later, sending now, or paused.
list_sends
ChatGPTCompleted email sends (broadcasts), newest first, with recipients and open/click/bounce/unsubscribe rates. Use get_send_report for one send in detail.
list_tags
ChatGPTList the workspace's contact tags with how many contacts carry each.
preview_audience
ChatGPTDry-run audience rules: how many contacts match right now plus a few sample emails. Nothing is saved. Use it before create_audience / update_audience to check the segment is the size you expect.
preview_bulk_contact_action
ChatGPTPreview a one-off bulk change to many contacts, without applying it: - add_tag / remove_tag: tag or untag everyone matching rules (audience rule language). - suppress: mark active contacts with no opens/clicks for inactive_months (default 6) as cleaned, so they stop receiving email. They are kept, but this can't be undone from the app. Hard bounces and unsubscribes are already excluded from every send, so there is nothing to suppress for them. Returns affected_count (the contacts that would actually change, not everyone the filter matches), a sample, a one-line summary, and a confirmation_token. Show the summary to the user; once they approve, call apply_bulk_contact_action with the token (valid 15 minutes).
preview_send
ChatGPTStep 1 of sending a draft to contacts. Validates the send and returns the exact recipient count, sample recipients, the from-address and the timing, plus a confirmation_token (valid 15 minutes, single use). NOTHING is sent. Show the summary to the user and only call schedule_send with the token after they explicitly approve. Leave audience_ids empty to send to all active subscribers.
query_send_analytics
ChatGPTAggregate questions about past sends (bounded to the most recent ~100): - most_recent / single_send (pass send_name): one send's numbers - top_performing: best sends by open/click rate - period_overview: totals and averages over recent sends, with trend - engagement_locations: clicks by country - top_links: most-clicked links - audience_engagement: which audiences engage most - deliverability_health: bounce/complaint/unsubscribe health - revenue: attributed revenue (Stripe/Shopify connected)
replace_draft_content
ChatGPTReplace a draft's ENTIRE body with a new Tiptap document. Use this for a full rewrite or a brand-new layout; for changes to part of an email use edit_draft_blocks. Applied live to the collaborative editor.
schedule_send
ChatGPTStep 2: actually send (or schedule) the email previewed by preview_send. Pass its confirmation_token, and repeat the previewed subject, recipient_count and send_time so the user can see what they are approving; a mismatch with the preview is refused and nothing is sent. The send is exactly what was previewed. This emails real people and can't be undone once delivery starts. Call it only after the user explicitly approves the preview. A scheduled send can be cancelled with cancel_scheduled_send before it goes out.
search_contacts
ChatGPTFind contacts. Combine any of: search (matches email and field values), status, audience_id, tag (exact tag name) and rules (the same rule language as audiences). Paginated, newest first by default. For a count of a rule-defined segment use preview_audience, which is cheaper than paging.
send_test_email
ChatGPTSend a test of a draft to up to 5 addresses (counts toward the plan's monthly test-send allowance). Merge tags render with fallback values. Delivered in the background within a minute.
set_automation_active
ChatGPTTurn an automation on (it starts enrolling contacts and SENDING email) or off. Turning on runs the same checks as the app: verified sender email, a trigger and at least one action, valid steps, and the plan's active-automation limit. Only turn one on after the user has explicitly approved it. Turning on requires confirm: true.
trigger_custom_event
ChatGPTFire a custom event for one contact, which enrolls them in every active automation triggered by it (and may send email). properties become event values that eventProperty nodes can render. By default an unknown email is added as a contact first; set add_contact false to only fire for existing contacts.
unsubscribe_contact
ChatGPTUnsubscribe one contact from all marketing email, exactly as if they had clicked unsubscribe. Already-unsubscribed contacts are left as they are. This can't be undone through this server: only the contact can opt back in.
update_audience
ChatGPTChange an existing audience's name, emoji and/or rules. rules, when given, is the COMPLETE new rule set and replaces every existing rule, so reproduce the rules you're keeping (get_audience shows them). Membership is recomputed in the background.
update_draft_settings
ChatGPTRename a draft and/or set the subject line and preheader (preview text) its sends default to. Subjects and preheaders may personalize with {{merge.first_name}} or, with a fallback, {{merge.first_name|there}}.
update_theme
ChatGPTChange theme fields (field names and value formats come from get_theme's field_reference). This restyles EVERY email using the theme, so change only what the user asked for. For a "dark theme", set the light-mode color fields to a dark palette; dark_* fields only tune recipients who are in dark mode. Don't change canvas_width unless asked.
upsert_contact
ChatGPTCreate a contact, or update the existing one with this email. fields maps field data_names to values (unknown data_names are rejected; create them first with create_field). Tags in add_tags are created if needed. Updating never changes subscription status: an unsubscribed contact stays unsubscribed. New contacts only: double_opt_in: true sends the workspace's confirmation email and holds them as unconfirmed until they click it. trigger_automations: true enrolls them in active "subscribes" automations, as if they had just signed up.