{"openapi":"3.1.0","info":{"title":"SMTP2GO (BYOK) API","version":"0.1.0","description":"SMTP2GO (BYOK) lets an AI assistant read your own SMTP2GO data through the SMTP2GO API with a key you supply (API key (restrict its permissions to the read endpoints you need)). Read-only: 11 tools (get_email_cycle, get_email_summary, get_email_bounces, get_email_history, search_activity, search_sent_emails, list_sender_domains, list_single_sender_emails, view_suppressions, search_templates,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smtp2go.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smtp2go/docs"},"termsOfService":"https://connectorbay.com/byok-smtp2go/terms"},"servers":[{"url":"https://byok-smtp2go.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smtp2go/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_email_cycle":{"post":{"operationId":"get_email_cycle","summary":"Show the plan cycle: start and end date, emails used, emails remaining and the monthly allowance. Use for \"How many emai","description":"Show the plan cycle: start and end date, emails used, emails remaining and the monthly allowance. Use for \"How many emails have I used this month on SMTP2GO\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_email_cycleArguments","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_email_summary":{"post":{"operationId":"get_email_summary","summary":"Get one report of the last 30 days: emails sent, bounces, spam, unsubscribes, opens, clicks, rejects and the plan cycle.","description":"Get one report of the last 30 days: emails sent, bounces, spam, unsubscribes, opens, clicks, rejects and the plan cycle. Use for \"Give me an SMTP2GO summary of my recent email performance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Optional SMTP username to report on one user only.","title":"Username"}},"title":"get_email_summaryArguments","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_email_bounces":{"post":{"operationId":"get_email_bounces","summary":"Get a summary of bounces and rejects for the last 30 days: emails, rejects, soft bounces, hard bounces and bounce percen","description":"Get a summary of bounces and rejects for the last 30 days: emails, rejects, soft bounces, hard bounces and bounce percentage. Use for \"What is my SMTP2GO bounce rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Optional SMTP username to report on one user only.","title":"Username"}},"title":"get_email_bouncesArguments","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_email_history":{"post":{"operationId":"get_email_history","summary":"Get sending activity for a period grouped by sender address, SMTP user, domain or subaccount: emails used, bytes, opens,","description":"Get sending activity for a period grouped by sender address, SMTP user, domain or subaccount: emails used, bytes, opens, clicks, bounces, spam and unsubscribes. Use for \"Which sender address sent the most email on SMTP2GO last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_by":{"anyOf":[{"enum":["email_address","username","domain","subaccount"],"type":"string"},{"type":"null"}],"default":"email_address","description":"Group by email_address, username, domain or subaccount.","title":"Group By"},"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period, ISO 8601 UTC, for example 2026-01-01T00:00:00Z. Defaults to 30 days ago.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period, ISO 8601 UTC, for example 2026-01-31T23:59:59Z (default now).","title":"End Date"}},"title":"get_email_historyArguments","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/search_activity":{"post":{"operationId":"search_activity","summary":"Search email events (processed, delivered, opened, clicked, bounced, unsubscribed ...) by subject, sender or recipient. ","description":"Search email events (processed, delivered, opened, clicked, bounced, unsubscribed ...) by subject, sender or recipient. Returns up to 1,000 events per page with a continue token. Use for \"Which emails to jo@example.com were delivered or bounced on SMTP2GO\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to find in any search field (subject, sender, recipient).","title":"Search"},"search_subject":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text the subject must contain (case-insensitive).","title":"Search Subject"},"search_sender":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text the sender address must contain.","title":"Search Sender"},"search_recipient":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text the recipient address must contain.","title":"Search Recipient"},"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period, ISO 8601 UTC, for example 2026-01-01T00:00:00Z. Defaults to the start of today.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period, ISO 8601 UTC, for example 2026-01-31T23:59:59Z (default now).","title":"End Date"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many events to return (1 to 1000).","title":"Limit"},"continue_token":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the continue_token of the previous answer (leave out for the first page).","title":"Continue Token"}},"title":"search_activityArguments","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/search_sent_emails":{"post":{"operationId":"search_sent_emails","summary":"List sent emails with sender, recipient, status, delivery time, SMTP response and open counts; optionally only opened or","description":"List sent emails with sender, recipient, status, delivery time, SMTP response and open counts; optionally only opened or clicked ones. Each record also carries open details. Use for \"Which emails did I send through SMTP2GO yesterday and did they arrive\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period, ISO 8601 UTC, for example 2026-01-01T00:00:00Z. Defaults to the start of today.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period, ISO 8601 UTC, for example 2026-01-31T23:59:59Z (default now).","title":"End Date"},"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many emails to return (1 to 5000).","title":"Limit"},"opened_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return only emails opened at least once.","title":"Opened Only"},"clicked_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return only emails with a clicked link.","title":"Clicked Only"},"username":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails sent by this SMTP username or API key user.","title":"Username"},"continue_token":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the continue_token of the previous answer (leave out for the first page).","title":"Continue Token"}},"title":"search_sent_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/list_sender_domains":{"post":{"operationId":"list_sender_domains","summary":"List verified and pending sender domains with DKIM and return-path verification state and tracking subdomains. Use for \"","description":"List verified and pending sender domains with DKIM and return-path verification state and tracking subdomains. Use for \"Are my SMTP2GO sender domains verified\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional: only this domain, for example 'example.com'.","title":"Domain"},"subaccount_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional subaccount ID to run this on behalf of a subaccount.","title":"Subaccount Id"}},"title":"list_sender_domainsArguments","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_single_sender_emails":{"post":{"operationId":"list_single_sender_emails","summary":"List single sender email addresses with their verification status. Use for \"Which single sender addresses do I have on S","description":"List single sender email addresses with their verification status. Use for \"Which single sender addresses do I have on SMTP2GO\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email_address":{"anyOf":[{"maxLength":254,"type":"string"},{"type":"null"}],"default":null,"description":"Optional: only this address.","title":"Email Address"},"subaccount_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional subaccount ID to run this on behalf of a subaccount.","title":"Subaccount Id"}},"title":"list_single_sender_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/view_suppressions":{"post":{"operationId":"view_suppressions","summary":"List suppressed addresses and domains with reason, type and time; check whether one address is blocked. Use for \"Is jo@e","description":"List suppressed addresses and domains with reason, type and time; check whether one address is blocked. Use for \"Is jo@example.com on my SMTP2GO suppression list\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email_address":{"anyOf":[{"maxLength":254,"type":"string"},{"type":"null"}],"default":null,"description":"Check one address or domain in the block list.","title":"Email Address"},"suppression_type":{"anyOf":[{"enum":["manual","spam","unsubscribe","bounce"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this type: manual, spam, unsubscribe or bounce.","title":"Suppression Type"},"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period, ISO 8601 UTC, for example 2026-01-01T00:00:00Z. Defaults to the start of today.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest time to look back to, ISO 8601 UTC (default 30 days before).","title":"End Date"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction: asc or desc.","title":"Sort Direction"},"continue_token":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the continue_token of the previous answer (leave out for the first page).","title":"Continue Token"},"subaccount_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional subaccount ID to run this on behalf of a subaccount.","title":"Subaccount Id"}},"title":"view_suppressionsArguments","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/search_templates":{"post":{"operationId":"search_templates","summary":"List email templates with name, id, subject, tags and last update. Use for \"Which email templates do I have on SMTP2GO\".","description":"List email templates with name, id, subject, tags and last update. Use for \"Which email templates do I have on SMTP2GO\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fuzzy_search":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to match search terms with wildcards.","title":"Fuzzy Search"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction: asc or desc.","title":"Sort Direction"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many templates to return (default 100).","title":"Page Size"},"continue_token":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the continue_token of the previous answer (leave out for the first page).","title":"Continue Token"}},"title":"search_templatesArguments","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/search_subaccounts":{"post":{"operationId":"search_subaccounts","summary":"List subaccounts with name, email, id, plan size, usage, state and dedicated IP flag. Use for \"Which SMTP2GO subaccounts","description":"List subaccounts with name, email, id, plan size, usage, state and dedicated IP flag. Use for \"Which SMTP2GO subaccounts do I have and how much have they sent\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"states":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"all","description":"Which states: all, active, closed, suspended or others as listed by SMTP2GO (default all).","title":"States"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction: asc or desc.","title":"Sort Direction"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many subaccounts to return (default 100).","title":"Page Size"},"continue_token":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the continue_token of the previous answer (leave out for the first page).","title":"Continue Token"}},"title":"search_subaccountsArguments","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}}}}