io.github.Synter-Media-AI/synter-ads

Attach Priority/hand-picked leads to an existing Synter Prospector (EmailBison) campaign by numeric campaign_id. Accepts structured lead objects and/or CSV-shaped rows (email,first_name,last_name,company,title,linkedin_url,custom_shows) and an optional per-lead custom_variables list/object forwarded to EmailBison merge tokens (custom_shows becomes CUSTOM_SHOWS). IDEMPOTENT AND RESUMABLE: safe to re-run with the same leads — saves dedupe by email, the push reconciles against live campaign membership, and a re-run refreshes stale custom variables on already-attached leads instead of duplicating them. Work is time-budgeted: on a large cohort this returns complete=false with remaining_emails, and you should call it again with only those leads. Saves into the Prospector leads table then IcyPeas-verifies and gate-pushes via verify_and_push_leads. Defaults grade=A and outreach_tier=TIER_1 for Priority A cohorts; override per lead or via grade/outreach_tier args. Tenant-scoped like other prospector_* tools — unmapped orgs are refused. Does not launch the campaign. No live prod push without Growth GO. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Attach explicitly selected sending inbox IDs to a Synter Prospector campaign. Requires a non-empty sender_email_ids array; never defaults to every inbox. Each ID must satisfy API-key inbox restrictions and the upstream authenticated sending workspace. Does not launch the campaign. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Create a draft Synter Prospector outbound campaign with a sending schedule in the authenticated workspace. List campaigns first to avoid duplicates. Defaults to plain_text=true and open_tracking=false (tracking pixels and HTML wrappers depress deliverability on cold outbound); pass plain_text=false only when the sequence genuinely needs HTML. Change either later with prospector_update_campaign_settings. This does not launch or send. Add copy separately with prospector_update_campaign_sequence. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Approve and deliver an AI-drafted reply to an interested prospect lead. NOTE: on customer-workspace MCP connections this tool is not yet tenant-scoped and is refused rather than served from Synter's house tenant; use it from the Synter-internal surface. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Collapse duplicate Prospector lead rows (same email) into one record: keeps the campaign-linked / most complete row, fills its gaps from the duplicates, moves related records onto it, and deletes the duplicates. dry_run defaults to TRUE; pass dry_run=false to apply. Pass emails to target specific addresses. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Get workspace-level Synter Prospector outbound analytics: campaign count, total replies, meetings booked, and per-campaign send/reply rates. Call this for an outbound reporting rollup across campaigns. [effect=read; scope=growth:read]

List bounced Prospector leads with a hard/soft/unknown split, the SMTP reason and code, the campaign, the sending inbox, and whether each address is already suppressed. Reads recorded bounces plus EmailBison's live bounced folder. Filter by campaign_id (numeric EmailBison id), since (ISO date), or bounce_type (hard/soft/unknown). [effect=read; scope=growth:read]

Get a Prospector outbound campaign by ID. Numeric sending-platform IDs read live campaign configuration and sequence steps; Prospector UUIDs read the client-scoped database snapshot. Numeric live readback requires the updated Prospector backend. [effect=read; scope=growth:read]

Get Synter Prospector outbound campaign performance: sends, opens, replies, meetings booked, and reply rate. Call this when reporting on an outbound sequence or comparing campaigns. Pass campaign_id for one campaign or omit it for the workspace rollup. [effect=read; scope=growth:read]

List Synter Prospector outbound campaigns with status, lead counts, replies, and schedule. [effect=read; scope=growth:read]

Get deliverability and warmup health for Prospector sending inboxes scoped to the authenticated owner. An empty result may indicate a missing owner-to-sending-domain mapping; it does not establish that reconnecting is necessary. [effect=read; scope=growth:read]

List leads in the Prospector outbound pipeline, or filter by campaign, pipeline status, tag, or free-text search. campaign_id accepts the numeric EmailBison campaign id (resolved against live campaign membership) as well as the internal UUID. status filters the pipeline stage (e.g. new, contacted, replied, meeting_booked). search matches email, name, or company. [effect=read; scope=growth:read]

Get high-level summary of Prospector outbound pipeline including leads, active campaigns, sent count, replies, meetings booked, and inbox health. [effect=read; scope=growth:read]

Get one saved Synter Prospector outbound report by id, including the metrics payload used for campaign reporting. Call prospector_get_reports first when the report_id is unknown. [effect=read; scope=growth:read]

List saved Synter Prospector outbound reports (campaign, step, and analytics artifacts). Call this to find a report_id before prospector_get_report. [effect=read; scope=growth:read]

Get per-step performance for a Synter Prospector outbound sequence (sends, replies, and drop-off by email or LinkedIn step). Call this after prospector_get_campaign_performance when a campaign reply rate needs a step-level diagnosis. [effect=read; scope=growth:read]

Reconcile a Prospector campaign's saved lead links with live EmailBison membership (numeric campaign_id): reports leads linked in Synter but not in EmailBison, EmailBison members not linked, and members with no saved lead, and returns the live member emails. dry_run defaults to TRUE; dry_run=false fixes the links in Synter only (never changes EmailBison). To detach invalid members use prospector_verify_leads then prospector_remove_leads. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Detach leads from ONE Synter Prospector (EmailBison) campaign by numeric campaign_id. mode=stop (default) stops future emails and keeps history; mode=remove deletes them from the campaign (irreversible, resets that lead's campaign history). Does not suppress globally. Pass dry_run=true to preview. Never sends email. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Globally suppress email addresses in Synter Prospector: adds them to the suppression list every push gate reads, blocklists them in EmailBison and stops future emails in every campaign holding them. A reason containing 'bounce' also records a hard bounce. all_workspaces=true fans the EmailBison blocklist/stop out to every workspace. Global scope and all_workspaces are limited to the Synter house workspace; tenants use prospector_remove_leads. Pass dry_run=true to preview. Never sends email. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Write email sequence steps on a Synter Prospector campaign in the authenticated workspace. mode=append (default) adds sequence_steps after the existing steps. mode=edit rewrites existing steps in place, addressed by step_id (read step ids with prospector_get_campaign); ids, order, inboxes, and schedule are kept and it is safe on a live campaign. mode=delete removes the steps in delete_step_ids; steps that have already sent cannot be deleted. mode=replace swaps the whole sequence and is refused on an active campaign. Every non-append write is verified against a live readback. Use <br> line breaks and {FIRST_NAME}, {COMPANY}, {TITLE} tokens. This does not launch or send. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Update sending settings on an existing Synter Prospector campaign in the authenticated workspace: plain_text (send as plain text rather than HTML), open_tracking (tracking pixel), can_unsubscribe, max_emails_per_day, max_new_leads_per_day, sequence_prioritization. Only the arguments you pass are changed. This never launches, pauses, or otherwise changes campaign status — use prospector_update_campaign_status for that. Campaigns created before this tool existed default to plain_text=false; set plain_text=true to stop sending HTML-wrapped cold email. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Pause, activate/resume, or archive a Prospector outbound campaign. Pass status=paused to stop sending, status=active (aliases: running, resume, launch, start, enabled) to call EmailBison launch_campaign, or status=archived to archive it (refused while active: pause first; history is kept). NOTE: on customer-workspace MCP connections this tool is not yet tenant-scoped and is refused rather than served from Synter's house tenant; use it from the Synter-internal surface. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Refresh EmailBison custom variables on leads ALREADY attached to a Synter Prospector campaign, without re-pushing them. Pass campaign_id plus leads=[{email, custom_variables}], where custom_variables is a list of {name, value} (names are uppercased by the backend, e.g. CUSTOM_SHOWS) or a plain {NAME: value} object. Idempotent: re-running overwrites the same variables. Use this when sequence merge tokens render blank or stale for leads that are already in the campaign. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Lower-level lead attach: IcyPeas-verify already-saved Prospector leads and gate-push them into an existing EmailBison campaign by numeric campaign_id. Each lead needs email + grade (A/B/C/D) + outreach_tier (TIER_1/TIER_2/TIER_3/EXCLUDE). Prefer prospector_add_leads for CSV-shaped Growth cohorts that still need save_leads_to_database. Idempotent on email within the campaign. Tenant-scoped. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Verify-only email check for Prospector leads: IcyPeas-verifies each address and returns valid / invalid / risky / unknown with the raw status, plus whether it is suppressed. No campaign, no push, no company-name gate, no domain cooldown. persist=true (default) records the verdict on your saved leads so the push gate can use it. Time-budgeted: re-call with `remaining` until complete=true. Up to 200 emails per call. [effect=write; scope=growth:write; requires=prospectorAccess; externalMutation=true]

Publish a GTM container — creates a version from the default workspace and publishes it. PUSHES ALL WORKSPACE CHANGES LIVE to the site's tracking immediately. Approval-gated. [effect=publish; scope=tracking:write; requires=campaignPublishing; externalMutation=true]

Publish a landing page draft, making it live at syntermedia.ai/lp/{slug} (free). A page that lost its last benchmark_landing_page run is refused until fixed or acknowledged. [effect=publish; scope=landing_pages:publish; requires=campaignPublishing; externalMutation=true]

Publish an approved, preflighted organic-post revision once to its exact bound destination. Requires separate publish approval and never automatically retries an ambiguous provider outcome. [effect=publish; scope=social:write; requires=campaignPublishing; externalMutation=true]

Publish a campaign plan for review, generating a shareable URL. Moves the plan from building/draft to in_review; a reviewer approves it at share_url, then execute_campaign_plan launches it. Runs plan QA (incl. the live tracking preflight) and pins the scorecard to the document. [effect=publish; scope=workspace:write; requires=campaignPublishing; externalMutation=true]

Create or update a private workspace skill from a complete SKILL.md document [effect=write; scope=skills:write]

Publish a markdown blog post to a connected GitHub repo: commit <content_path>/<slug>.md and open a PR for the customer to review and merge (never pushes directly). Free. [effect=publish; scope=workspace:code; requires=campaignPublishing; externalMutation=true]

Get Amazon Ads (Sponsored Products/Brands/Display) metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Amazon reporting retains about 90 days, so windows are capped there. When counting 'live' campaigns, only count campaigns with state=ENABLED AND active ad groups with budget remaining — ARCHIVED campaigns are NOT active. IMPORTANT: If the user has multiple Amazon Ads accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Pull Amazon DSP campaign performance data (2 credits) Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Amazon reporting retains about 90 days, so windows are capped there. [effect=read; scope=reporting:read]

Get Campaign Manager 360 (CM360) metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Use account_name to specify which account when multiple are connected. [effect=read; scope=reporting:read]

Get Criteo Commerce Media metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Returns displays, clicks, cost, conversions, and revenue per campaign. [effect=read; scope=reporting:read]

Get Display & Video 360 (DV360) metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Use account_name to specify which account when multiple are connected. [effect=read; scope=reporting:read]

Get FreeWheel Buyer Cloud (Beeswax) metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges, or days for a rolling window. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. Use account_name to specify which account when multiple are connected. [effect=read; scope=reporting:read]

Get Google Ads campaign metrics — impressions, clicks, spend, conversions per campaign (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges like weekends, or days for a rolling window. last_N_days presets cover the N complete days ending YESTERDAY (Google Ads semantics; use date_range=today for today). segment=date|week breaks metrics out per day or per week (one call for a pacing or creative-fatigue trend — don't loop one call per week). Paginate with limit/offset (next_offset in the result); at level=ads set include_ad_text=false to fit several hundred ads per page. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. IMPORTANT: If the user has multiple Google Ads accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Get Instacart Ads metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Returns impressions, clicks, spend, attributed orders, and attributed sales per campaign. [effect=read; scope=reporting:read]

Get LinkedIn Ads metrics — impressions, clicks, spend, conversions per campaign (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges, or days for a rolling window. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. Pass campaign_group_ids (comma-separated) to filter to specific campaign groups. IMPORTANT: If the user has multiple LinkedIn accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Pull LinkedIn Ads Company Engagement report — shows which companies have seen your ads and how engaged they are (2 credits) [effect=read; scope=reporting:read]

Get Meta (Facebook/Instagram) Ads metrics — impressions, clicks, spend, conversions per campaign (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges, or days for a rolling window. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. IMPORTANT: If the user has multiple Meta Ads accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Get Microsoft (Bing) Ads metrics — impressions, clicks, spend, conversions per campaign (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges, or days for a rolling window. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. IMPORTANT: If the user has multiple Microsoft Ads accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Get OpenAI Ads metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Pulls insights from the OpenAI Ads API. Optional scope: campaign_id, ad_group_id, or ad_id to scope the report. Defaults to the selected scope's natural aggregation level; unscoped defaults to ad_account. [effect=read; scope=reporting:read]

Get Pinterest Ads metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. IMPORTANT: If the user has multiple Pinterest ad accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Get Reddit Ads metrics — impressions, clicks, spend, conversions per campaign (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges, or days for a rolling window. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. IMPORTANT: If the user has multiple Reddit Ads accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]

Get Snapchat Ads metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Use account_name to specify which account when multiple are connected. [effect=read; scope=reporting:read]

Get Spotify Ads metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Use account_name to specify which account when multiple are connected. [effect=read; scope=reporting:read]

Get Target Roundel retail media metrics (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for a fixed historical range, or days for a rolling window. Returns impressions, clicks, spend, conversions, and revenue per campaign. [effect=read; scope=campaigns:read]

Get TikTok Ads metrics — impressions, clicks, spend, conversions per campaign (2 credits). Date window: date_range preset (today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, last_180_days, last_365_days, last_2_years, last_3_years), start_date/end_date (YYYY-MM-DD) for custom ranges, or days for a rolling window. Any window up to 3 years (1095 days) is accepted; long windows are fetched in platform-sized chunks and stitched, and `truncated`/`warnings` in the result say when a read was bounded. For detailed video engagement metrics use tiktok_ads_get_insights. IMPORTANT: If the user has multiple TikTok Ads accounts connected, you MUST ask which account to use BEFORE calling this tool — pass account_name to select it. [effect=read; scope=reporting:read]