How to connect AffiliateSpy MCP with Python

Your AffiliateSpy plan and usage: plan name, caps, contact reveals used/left this month (resets on the 1st, UTC), and tracked apps used vs cap.

Apps you track, with creator counts and the latest scan status per app. Use an app's id as app_id in other tools.

Latest scan run for an app (stages, status, creators found). Starting scans: start_quick_scan (free preview, no plan needed) or start_scan (guarded, plan required).

Creators for an app, sanitized: contact VALUES are hidden until revealed with reveal_contact (revealed emails are included). graded:false marks a preview row not graded yet (grade and score null). Sorted by score descending unless `sort` is set. Paginate with limit/offset; response includes total after filters.

Full detail for one creator: grade reasoning, evidence receipts, recent posts metadata, cross-platform profiles, monetization signals. Contact value stays hidden unless already revealed.

Spend ONE monthly reveal to get a creator's contact value (email / IG handle / bio link). Idempotent: re-revealing an already-revealed creator returns the same value without spending again. Errors: no_subscription, cap_reached, no_contact.

Roundup articles, affiliate sites and videos promoting your competitors, best fit first (acceptance score), with SERP position, competitors featured, per-receipt link facts, and whether YOUR app is featured. Sites flagged out of outreach (review_reason) are left out unless include_flagged is set.

Your competitors with roster counts: how many creators are proven paid partners of each, how many mention each, how many distinct sites promote each, plus creators promoting 2+ brands in your niche. sites_promoting_any counts each site once however many competitors it promotes.

Search keywords we track for your app, plus per-keyword roundup coverage (how many roundups, how many feature a competitor, whether any feature you).

Add a creator to your saved list (the shortlist campaigns draw from).

Remove a creator from your saved list.

Attach or replace your private note on a creator (max 4000 chars). Empty string clears it.

Your outreach campaigns with stats (sent, replies, queued, signed). v1 tools can only create DRAFTS, launching, pausing and sending happen in the dashboard at https://affiliatespy.io/dashboard/campaigns.

One campaign's settings, sequence templates, enrollment rows and latest reply previews.

Create a DRAFT outreach campaign from creator ids (or your saved list) with the default 4-step sequence. DRAFT ONLY, this tool cannot launch, enroll, or send. Review and launch in the dashboard at https://affiliatespy.io/dashboard/campaigns.

Outreach conversation threads (metadata + last activity; message bodies via get_thread). Replying happens in the dashboard, no tool can send email.

One inbox thread with full message bodies. To reply, use the dashboard inbox at https://affiliatespy.io/dashboard/inbox, no tool can send email.

Your pipeline: deals by stage (contacted, negotiating, live, paid) plus replied creators not yet in the pipeline.

Move a pipeline deal to a new stage.

CSV of your creator list (same filters as list_creators). Paid feature, requires an active subscription, same gate as the dashboard export. Emails appear ONLY for creators you have revealed.

Launch a DRAFT campaign: enrolls only creators with a REVEALED email (others reported as excluded) and sets it active, the engine then sends on its own schedule, window and daily cap. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Pause an active campaign (stops future sends; nothing is deleted). Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Resume a paused campaign (sends continue under the engine's window and caps). Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Send an email reply in an inbox thread, the SAME gated path as the dashboard composer: subscription, daily send cap, Gmail connection and the OUTREACH_TEST_MODE redirect are all enforced inside the send function. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Start a creator scan for an app (spends scan credits). Same gates as the dashboard: active subscription required, and a queued/running scan for the app refuses with scan_in_progress. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

The Discovery Autopilot's state for one project (default: the project it runs for): status on/off for this project, as the Autopilot page shows it (autopilot_status and running_for say whether it runs for another project), the commission offer it may promise, today's send count vs cap, what it is waiting on before it can recruit, the approval queue (campaign launches, website batches, reply drafts and check-ins waiting for a human), and recent approved/rejected activity. held_by_breaker means autopilot is bound here but the bounce breaker is holding every send and proposal until set_autopilot on (or choosing a mailbox, per paused_reason) clears it. Read-only.

Turn the Discovery Autopilot on or off for one project, and/or set that project's commission offer drafts may promise. Autopilot runs for one project at a time: turning it on binds it to app_id (required until autopilot is bound to a project; default after that: the project it runs for). Turning it on starts the hourly proposal loop; new proposals wait for an approval unless the owner has set an auto mode on the Autopilot page. After the bounce breaker stopped the project's mailbox (get_autopilot's paused_reason for that project), turning it on for that project also clears that stop, restarts that mailbox's bounce count and resumes the campaigns the breaker paused for that mailbox, whose queued emails then send on the engine's schedule. Other mailboxes keep their stops, counts and paused campaigns. A stop whose mailbox was not recorded holds every project: turning autopilot on for any project clears it and restarts no count. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Approve a queued autopilot action and EXECUTE it. Depending on its type: a website batch enrols its sites and their cold first emails go out on the lane campaign's schedule; a sister-program intro, a welcome or a check-in is sent to that partner; a follow-up or a reply is sent into its thread; a campaign proposal reveals missing contacts (metered) and launches. The approval summary names what this one does, and an edit after it was shown needs a fresh approval. Same gated paths as the dashboard's approve button, including its edits: body replaces the drafted text, remove_ids drops sites from a website batch (they are flagged so autopilot never proposes them again). Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Reject a queued autopilot action with a reason. The reason is fed back into the drafter's prompt, so a specific reason improves future drafts. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Free quick scan of an App Store, Google Play or website URL: creates the tracked app and queues the scan. No plan needed (one quick-scan app per unpaid account, 6 an hour). Preview only (masked handles, no contacts). Accounts WITH a plan should use start_scan for the full scan instead. Takes 20 to 60 seconds to return because the intake (competitors, search queries) runs first; then call get_quick_scan_preview, which waits server-side until the scan is done.

Progress and locked preview rows for a quick scan (platform, followers, a hint like '★ <competitor> partner', masked handle; no real handles or contacts). Long-polls: waits server-side (default 45 seconds) until the scan status is done or failed, so one call is usually enough; call again while status is queued or running. Use it to show the user what a paid plan unlocks, then get_checkout_link.

Stripe Checkout URL for a plan (starter $99, growth $299, agency $799 a month; yearly = two months free). The USER opens it and pays in the browser; never enter payment details yourself. On an active Stripe subscription the plan is switched in place (prorated) and a settings URL is returned instead. Access is granted by the payment webhook, so call get_account afterwards.

One site's full detail, as the Websites drawer shows it: every page on the site with the competitors it features and its affiliate and backlink receipts, prospect status, fit score, contact (email, name, where it came from, last check, error), your note, review flags, signed-up state, and every campaign enrolment with its enrollment_id (for get_thread) and Gmail thread id. Read-only.

Set a site's prospect status, as the Websites status menu does: new, prospect (picked for outreach), contacted, replied, signed_up (joined your program), rejected (said no) or ignored (set aside). Autopilot proposes only sites at new (link exchange: new or prospect) and campaigns enrol only new or prospect sites, so signed_up, rejected and ignored keep a site out of outreach. Nothing is sent.

Enter a site's contact email by hand, as typing one in the Websites drawer does: checked against the outreach policy (legal, privacy and system mailboxes are refused) and saved as a manual contact, replacing a found one. Sites already enrolled keep the address they were enrolled with. Nothing is sent.

Attach or replace your private note on a site (max 4000 chars). Empty string clears it.

Find a contact email for up to 25 sites, as the Websites Find email button does: the free chain first (cache, the site's contact pages, policy and deliverability checks), then ONE paid contact-finder lookup per site when that finds nothing and the project's monthly finder budget has room. Found addresses (and the contact's name when known) are saved on the site. Sites that already show a contact path are skipped, as in the dashboard. Runs one site at a time for up to about four minutes; sites not reached come back as not_started. Nothing is sent. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Add sites to a campaign, as Add to campaign on the Websites tab does. A draft only grows its audience (nothing sends until launch). An active or paused campaign ENROLS them now through the enrol gate: a site needs a contact email, a clean review, status new or prospect, no earlier contact by either product, no opt-out or bounce, and must not be a competitor's or your own site; enrolled sites get the campaign's first email on the engine's schedule, window and daily cap (a paused campaign once resumed). Counts say why sites were skipped. Campaigns written for creators refuse websites. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Add creators to a campaign, as Add to campaign on the Creators tab does. A draft only grows its audience (nothing sends until launch). An active or paused campaign ENROLS them now: only creators with a REVEALED email that never opted out or bounced; the rest come back as excluded (dm_only have no email at all). Enrolled creators get the campaign's first email on the engine's schedule, window and daily cap. Campaigns written for websites refuse creators. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Create a DRAFT campaign for sites from list_websites (one project), with the website sequence autopilot's affiliate lane sends unless you pass steps, and an optional schedule. The copy must pass the same check enrolment runs (rendered for a sample site: no links, bare domains, stock phrases, unknown tokens or empty offer), else nothing is created. Website copy personalises with tokens such as {{greeting}}, {{opener}}, {{tease_pitch}}, {{offer_pitch}} and {{signoff}}: get_campaign shows a campaign's templates and preview_campaign_step renders one for a site. DRAFT ONLY: nothing is enrolled or sent; launch_campaign (guarded) starts it.

Edit one step of a campaign's email sequence (subject, body, delay), as the dashboard's email editor does; on a live campaign the change applies to every enrolled recipient's next unsent step. Follow-ups always reply in step 1's thread as Re: plus its subject, so subject is for step 1 only. Website copy must pass the check enrolment runs (no links, bare domains, stock phrases, unknown tokens or empty offer), else nothing is saved. Website copy personalises with tokens such as {{greeting}}, {{opener}}, {{tease_pitch}}, {{offer_pitch}} and {{signoff}}: get_campaign shows a campaign's templates and preview_campaign_step renders one for a site.

Change a DRAFT campaign's setup, as Finish setup saves it: name, offer, daily limit, sending days and hours, timezone and follow-up gaps. Fields you omit keep their value. Live campaigns refuse (not_a_draft): rename them with rename_campaign and edit copy with update_campaign_sequence. Nothing is sent.

Rename a campaign (any status). Nothing else changes.

Copy a campaign as a new DRAFT: same audience, sequence and settings, no enrolments. Nothing is sent until the copy is launched.

Delete a campaign, as the dashboard does: it leaves every list and its queued emails stop. Enrolments and messages stay as contact history, so nobody in it can be emailed again from scratch, and late replies still reach the Inbox. The dashboard has no undo. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

The exact email one step sends to one site: subject and body rendered the way the send engine renders them (program facts, offer ladder, the site's page and receipts, its contact name, an approved opener, the opt-out footer and postal address), for a website campaign, or without campaign_id for an autopilot lane's campaign (its default sequence before autopilot made one). refused_at_send names a content rule the send would fail. Read-only.

Quality hints for an email draft, the same check the dashboard's editor and Inbox composer show: judged against the campaign's offer (or, without campaign_id, the project's program and the autopilot offer). Hints, up to 3: Reads as a template, Promises something not in your offer, Mentions a fee, Not safe to send without edits, Nothing specific about this creator. Pass the rendered email (preview_campaign_step gives it), not {{tokens}}. Read-only.

One autopilot queue or activity item in full, as the dashboard's approval card shows it: type, the lane (mode key) that governs it, status, error, the drafted email (to, subject, body, the original draft when edited), the thread it answers and their message, reply triage and QA flags, and for a website batch every site with its fit score, the competitors its page links to, its opener and any sensitive content label (selected:false means dropped). Read-only.

Hold an automatic item so it waits for an approval instead of acting on its own: a reply timed to send by itself (auto_send_after) or a website batch of a lane on auto. Use before reviewing or rejecting one. Items that already wait for an approval are left as they are. not_found: it already went out, or is not pending.

Set what autopilot may do on its own in one lane. Modes are per account and apply to whichever project autopilot runs for. Allowed values per lane: websites: approve|auto|off; featured: approve|auto|off; link_exchange: approve|off; replies: approve|auto_simple; nudges: approve|off; cross_sell: approve|off; retouch: approve|off; chase: approve|off; creators: approve|off; proof_line: on|off. approve queues every proposal for an approval; off proposes nothing; auto (websites, featured) and auto_simple (replies) act without a click once their unlock rule holds. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Set a project's fit floor (0 to 100): the least fit score a site needs for autopilot's affiliate prospects batches and the paid email finder. get_autopilot shows it as floor and ready_sites.

Mark every unread message in an inbox thread as read, as opening it in the dashboard does.

Undo an opt-out the reply reading recorded on a thread (a misread, such as "remove me as the contact, write to partners@"). Only opt-outs this account's own reply reading listed are removed; a click on the unsubscribe link or another sender's opt-out stays. The thread goes back to replied with no more sequence steps, and the contact can be emailed again. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Put a creator in the pipeline, from a creator id or an inbox thread. One deal per creator: on an existing deal it moves the stage. Website threads have no deals yet (they arrive with the partner sync); track a site by its status instead.

Set a deal's value, type, notes or follow-up date. Omitted fields stay; null clears value or follow-up date. Stage moves: move_deal_stage.

Everything App settings shows for a project. offer: the stored offer fields update_offer edits (absent: unset, the legacy program fills it; empty or null: cleared). program_facts: what outreach actually uses. follow_up_schedule: the day each email goes out and the rate it offers (rate null: the commission line as written, or a reminder). sending: effective daily cap, reply reserve and morning contact checks (max is the platform ceiling), today's cap under the mailbox warm-up, paid finder budget, window, timezone and days. Also notifications and re-scan cadence, product summary, market, marketing domain, Play link and the autopilot fit floor.

Change any of the project's offer fields (App settings, Your offer); fields you leave out keep their value. Strings: empty clears. Numbers: null clears. Saved through the same validation as the dashboard. Applies to the next email. Returns the stored offer.

Sending limits and defaults (App settings, Sending); fields you leave out keep their value. The daily cap and reply reserve belong to the mailbox, so every project sending from it gets them. Values are clamped as in the dashboard; the response has what now applies. Window, timezone and days are the defaults every new campaign starts with. Guarded, since the cap and the paid finder budget change how much mail goes out and what it costs. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Product summary, market, marketing domain, Google Play link, re-scan cadence and notification emails; fields you leave out keep their value. A changed summary re-grades every graded creator against it (no scan, nothing spent), as saving it in the dashboard does; the response says how many. The market applies from the next scan.

The project's sending health (App settings, Sending): the From domain check (SPF covers Google, DKIM, DMARC policy, MX, MTA-STS, Spamhaus blocklist, with errors and warnings in plain words), the separate outreach domain, the mailbox warm-up (week 1 to 3 caps 10, 20, 30 a day; established skips it), seed inboxes and how their results are read, and the latest inbox placement test: which tab each seed got each step in (primary, promotions, updates, spam, missing), whether it covers the current template, and the gate verdict.

Check the project's From domain DNS again now (after a fix) instead of waiting for the daily check. Returns the deliverability view.

A separate domain for the project's cold mail: live sending accepts a From on it as on the project's own domain, with the same domain check and warm-up. Empty string clears it. Free mailbox domains (gmail.com) never qualify.

Mark the project's mailbox established (true: no warm-up, the full daily cap applies at once) or not (false: the warm-up applies again). It belongs to the mailbox, so every project sending from it follows. Only for a mailbox with a sending history. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Add a seed inbox for inbox placement tests whose results the owner checks by hand (Outlook, Yahoo). Seeds belong to the account, not one project. For a Gmail seed whose results are read automatically, use get_seed_connect_link instead.

Remove a seed inbox (its Gmail access goes with it; past test results keep its address).

The link a human opens in a browser, signed in to AffiliateSpy, to connect a Gmail account as a seed inbox through Google's consent screen. The seed only receives tests and is read for where they land; it never sends and takes no mailbox slot. Do not open it yourself.

Send the template under test (step 1 and step 2, rendered as for a real prospect) from the project's mailbox to every seed inbox now, one message per seed and step. Seeds are the owner's own inboxes, so test mode does not redirect them. Refused without seeds, a mailbox with read access, a From that passes the live check, or valid content. Read the results a few minutes later with refresh_inbox_test_results. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

Read where the latest inbox test's messages landed in each Gmail seed now, rather than at the next reply check. Returns the deliverability view.

Every connected Gmail mailbox: read access (needed to see replies and bounces), free mailbox flag, over the plan's mailbox limit, warm-up, the Send mail as aliases Gmail lists and whether it accepted each, and the projects sending from it with their alias. project: the given (or newest) project's mailbox and From. Connecting, disconnecting and revoking happen in the dashboard.

Make the project send from one of your connected mailboxes (id from get_mailboxes). Follow-ups already running from its previous mailbox stop. If the bounce breaker stopped that mailbox, the project's active campaigns pause first. alias_verified says whether Gmail accepts the project's alias there.

The address the project's email goes out as: a Send mail as alias Gmail has verified on the project's mailbox (refused otherwise, with the accepted ones). Empty string clears it, so mail goes out as the mailbox address.

Remove the project's mailbox link. Nothing sends for the project, and its inbox threads cannot be answered, until a mailbox is set again. The Google account stays connected (disconnecting happens in the dashboard).

The link a human opens in a browser, signed in to AffiliateSpy, to connect a Gmail mailbox through Google's consent screen; it is linked to the project afterwards. With reconnect, it re-consents that connected mailbox instead (for example to grant read access). Do not open it yourself.

Add a competitor to a project by domain or URL; the next scan mines its affiliates deep. Same rules as the Competitors page: the plan's competitor cap (too_many) and a brand already on the list (already_tracked). Undo with remove_competitor.

Take a competitor off a project's list. It is remembered as removed, so suggestions never bring it back, and restore_competitor with the same competitor value puts it back where it was (only the last removal).

Undo the last remove_competitor (or a swap) on a project: the competitor goes back where it was, exactly as stored. Refused with nothing_to_restore when a later removal replaced it, and too_many at the cap.

The Competitors page's Suggested rail: up to 12 brands the scans found that are not on the list, best first, with why (sites that co-promote them, bumps, a program, paid ads, App Store similar, shared searches), and swap_out: at the cap, the mined competitor with the fewest receipt sites that a swap would take out. Read-only.

Add a suggestion from get_competitor_suggestions to the list (mined deep on the next scan), as the rail's Add does. At the cap, pass swap_out_id to take out a competitor already mined deep in the same write, as the rail's Swap does. Undo an add with remove_competitor; undo a swap with restore_competitor (competitor: swap_out_id, replacing: the new id).

Hide a suggestion for good (later scans keep the choice). undo: true puts a dismissed suggestion back on the rail.

Track a search keyword on a project (30 at most). A keyword you add is searched first by every sweep. To undo remove_keyword, pass its undo.restore so the keyword goes back where it was.

Stop tracking a search keyword on a project. The result's undo is the add_keyword call that puts it back where it was.

How the project's commission offer compares with its competitors' published programs: their rates and cookie windows, the market median, how many open prospect sites promote a program paying more, a terms chip per competitor domain with its source, and the affiliate program directories the competitors are listed on. benchmark null when no competitor program terms were found yet. Read-only.

Everyone already promoting the project, as the Partners page shows it: creators in a live or paid deal, sites featuring you, and your affiliate program's roster with per-affiliate clicks, conversions, revenue and commission (cents). Tabs: active, pending, lost, nofollow (sites linking without passing authority), missing_email. counts covers every tab. Read-only.

The project's affiliate program connection, as the Autopilot page's card shows it: provider, program id, status, affiliates (approved, pending, inactive), revenue and commission, last sync, last error and signup approval mode; and the program's recent sales stats (conversions, average payment, commission, top affiliate's commission, window hours) when a sync stored them. Connecting or disconnecting a program takes an API key, so it happens in the dashboard (https://affiliatespy.io/dashboard/autopilot). Read-only.

Queue an immediate sync of an affiliate program connection, as the card's Sync now does: roster, signup matching and sales stats. It runs in the background; read get_program's last_synced_at a minute or two later.

How a program connection handles new affiliate signups: approve (ask first: you approve them in your program), auto (each sync approves pending signups your outreach recruited; others still wait) or off. Guarded: auto approves real signups in your program, which may email them. Guarded: without approval_token it returns {error:"approval_required", approval_token, summary} for the user to confirm; call again with the token. Every dashboard guardrail still applies: this is exactly what a user clicking the dashboard could do, no more.

The project's Overview metrics (live partners, signed up, recruited by outreach, converting, in outreach, contacted, replied, reply rate, prospects, with contact, lost, competitors tracked), each one's change over 7, 30 and 90 days (null until a daily snapshot that old exists), and the sites each competitor gained in the last 7 days. Read-only.