{"openapi":"3.1.0","info":{"title":"Instantly (BYOK) API","version":"0.1.0","description":"Instantly (BYOK) lets an AI assistant read your own Instantly data through the Instantly API with a key you supply (API v2 key (create it with read scopes only)). Read-only: 12 tools (get_workspace, list_campaigns, get_campaign, get_campaign_analytics, get_analytics_overview, get_daily_campaign_analytics, list_email_accounts, list_lead_lists, list_leads, get_lead, list_emails,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-instantly.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-instantly/docs"},"termsOfService":"https://connectorbay.com/byok-instantly/terms"},"servers":[{"url":"https://byok-instantly.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-instantly/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_workspace":{"post":{"operationId":"get_workspace","summary":"Show the Instantly workspace the key belongs to: name, owner and which plans are attached. Use for \"Which Instantly work","description":"Show the Instantly workspace the key belongs to: name, owner and which plans are attached. Use for \"Which Instantly workspace is this key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_workspaceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_campaigns":{"post":{"operationId":"list_campaigns","summary":"List campaigns of the workspace with name, status number and timestamps. Statuses: 0 draft, 1 active, 2 paused, 3 comple","description":"List campaigns of the workspace with name, status number and timestamps. Statuses: 0 draft, 1 active, 2 paused, 3 completed, 4 running subsequences, -1 accounts unhealthy, -2 bounce protect, -99 suspended. Use for \"Which of my Instantly campaigns are active right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_starting_after value from the previous answer to get the next page.","title":"Starting After"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only campaigns whose name contains this text.","title":"Search"},"status":{"anyOf":[{"enum":[-99,-1,-2,0,1,2,3,4],"type":"integer"},{"type":"null"}],"default":null,"description":"Only campaigns with this status number.","title":"Status"}},"title":"list_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_campaign":{"post":{"operationId":"get_campaign","summary":"Get one campaign's settings: name, status, daily limit, tracking switches and timestamps. Use for \"Show the settings of ","description":"Get one campaign's settings: name, status, daily limit, tracking switches and timestamps. Use for \"Show the settings of Instantly campaign 0198a3b0-1111-7222-8333-444455556666\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Campaign id (UUID) from list_campaigns.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_campaignArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_campaign_analytics":{"post":{"operationId":"get_campaign_analytics","summary":"Get send, open, reply, click, bounce and opportunity counts per campaign, for one campaign or all of them, optionally wi","description":"Get send, open, reply, click, bounce and opportunity counts per campaign, for one campaign or all of them, optionally within a date range. Use for \"How many emails did each Instantly campaign send and how many replies did it get\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Campaign id to limit the answer to one campaign; leave empty for all campaigns.","title":"Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, formatted YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to include, formatted YYYY-MM-DD.","title":"End Date"},"exclude_total_leads_count":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to skip the total leads count, which makes the call much faster.","title":"Exclude Total Leads Count"}},"title":"get_campaign_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_analytics_overview":{"post":{"operationId":"get_analytics_overview","summary":"Get one combined set of totals (sent, opens, replies, clicks, bounces, interested, meetings booked, closed) across campa","description":"Get one combined set of totals (sent, opens, replies, clicks, bounces, interested, meetings booked, closed) across campaigns, optionally for one campaign or a date range. Use for \"What are my overall Instantly reply and meeting totals this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Campaign id to limit the totals to one campaign; leave empty for all.","title":"Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, formatted YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to include, formatted YYYY-MM-DD.","title":"End Date"},"campaign_status":{"anyOf":[{"enum":[-99,-1,-2,0,1,2,3,4],"type":"integer"},{"type":"null"}],"default":null,"description":"Only include campaigns with this status number.","title":"Campaign Status"}},"title":"get_analytics_overviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_daily_campaign_analytics":{"post":{"operationId":"get_daily_campaign_analytics","summary":"Get day-by-day sent, opened, reply, click and opportunity counts for one campaign or all campaigns. Use for \"Show my Ins","description":"Get day-by-day sent, opened, reply, click and opportunity counts for one campaign or all campaigns. Use for \"Show my Instantly daily sends and replies for the last two weeks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Campaign id; leave empty for all campaigns.","title":"Campaign Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, formatted YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to include, formatted YYYY-MM-DD.","title":"End Date"},"campaign_status":{"anyOf":[{"enum":[-99,-1,-2,0,1,2,3,4],"type":"integer"},{"type":"null"}],"default":null,"description":"Only include campaigns with this status number.","title":"Campaign Status"}},"title":"get_daily_campaign_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_email_accounts":{"post":{"operationId":"list_email_accounts","summary":"List the sending email accounts connected to the workspace with status (1 active, 2 paused, negative values are errors),","description":"List the sending email accounts connected to the workspace with status (1 active, 2 paused, negative values are errors), daily limit and warm-up status. Use for \"Are all my Instantly sending accounts healthy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_starting_after value from the previous answer to get the next page.","title":"Starting After"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only accounts whose address contains this text.","title":"Search"},"status":{"anyOf":[{"enum":[1,2,3,-1,-2,-3],"type":"integer"},{"type":"null"}],"default":null,"description":"Only accounts with this status: 1 active, 2 paused, 3 maintenance, -1 connection error, -2 soft bounce error, -3 sending error.","title":"Status"}},"title":"list_email_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_lead_lists":{"post":{"operationId":"list_lead_lists","summary":"List the lead lists of the workspace with name and creation time. Use for \"What lead lists do I have in Instantly\".","description":"List the lead lists of the workspace with name and creation time. Use for \"What lead lists do I have in Instantly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_starting_after value from the previous answer to get the next page.","title":"Starting After"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only lists whose name contains this text.","title":"Search"}},"title":"list_lead_listsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_leads":{"post":{"operationId":"list_leads","summary":"List leads, optionally inside one campaign or lead list or matching a name or email search, with open, reply and click c","description":"List leads, optionally inside one campaign or lead list or matching a name or email search, with open, reply and click counts. Read-only search; ordered by lead id. Use for \"Which leads in Instantly campaign 0198a3b0-1111-7222-8333-444455556666 have replied\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only leads of this campaign id.","title":"Campaign"},"list_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only leads of this lead list id.","title":"List Id"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text matched against first name, last name and email.","title":"Search"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many leads to return (1 to 100).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the next_starting_after value from the previous answer.","title":"Starting After"}},"title":"list_leadsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_lead":{"post":{"operationId":"get_lead","summary":"Get one lead by id: contact details, status, engagement counts and verification status. Use for \"Show Instantly lead 019","description":"Get one lead by id: contact details, status, engagement counts and verification status. Use for \"Show Instantly lead 0198a3b0-aaaa-7222-8333-444455556666\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Lead id (UUID) from list_leads.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_leadArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_emails":{"post":{"operationId":"list_emails","summary":"List emails in the unified inbox (sent and received) filtered by campaign, sending account, lead, unread flag or type. T","description":"List emails in the unified inbox (sent and received) filtered by campaign, sending account, lead, unread flag or type. This endpoint is limited to 20 calls per minute. Use for \"Show unread replies in my Instantly inbox\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_starting_after value from the previous answer to get the next page.","title":"Starting After"},"campaign_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails of this campaign id.","title":"Campaign Id"},"eaccount":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails sent or received by this sending account address.","title":"Eaccount"},"lead":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails with this lead email address.","title":"Lead"},"is_unread":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for unread emails only.","title":"Is Unread"},"email_type":{"anyOf":[{"enum":["received","sent","manual"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by type: received, sent or manual.","title":"Email Type"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Order by creation date: asc or desc.","title":"Sort Order"},"preview_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to return only a short preview of each email.","title":"Preview Only"}},"title":"list_emailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_unread_emails":{"post":{"operationId":"count_unread_emails","summary":"Count the unread emails in the workspace unified inbox. Use for \"How many unread emails are in my Instantly inbox\".","description":"Count the unread emails in the workspace unified inbox. Use for \"How many unread emails are in my Instantly inbox\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"count_unread_emailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}