{"openapi":"3.1.0","info":{"title":"SocketLabs (BYOK) API","version":"0.1.0","description":"SocketLabs (BYOK) lets an AI assistant read your own SocketLabs data through the SocketLabs API with a key you supply (SocketLabs API key (created with the 'SocketLabs Api' access option)). Read-only: 12 tools (get_usage_summary, list_sending_domains, list_bounce_domains, list_dkim_entries, list_tracking_domains, get_delivery_overview, get_failures_overview, list_failed_messages,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-socketlabs.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-socketlabs/docs"},"termsOfService":"https://connectorbay.com/byok-socketlabs/terms"},"servers":[{"url":"https://byok-socketlabs.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-socketlabs/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_usage_summary":{"post":{"operationId":"get_usage_summary","summary":"Show a server's current billing period, plan name and cost, messages and bandwidth used against the plan allowance. Use ","description":"Show a server's current billing period, plan name and cost, messages and bandwidth used against the plan allowance. Use for \"How many emails have I used so far this billing period on SocketLabs server 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"}},"required":["server_id"],"title":"get_usage_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/list_sending_domains":{"post":{"operationId":"list_sending_domains","summary":"List a server's sending domains with verification status, authentication status and StreamScore. Use for \"Which sending ","description":"List a server's sending domains with verification status, authentication status and StreamScore. Use for \"Which sending domains on SocketLabs server 12345 are authenticated\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"domain","description":"Field to sort by, for example domain.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id"],"title":"list_sending_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_bounce_domains":{"post":{"operationId":"list_bounce_domains","summary":"List a server's custom bounce domains and which one is the default. Use for \"Which bounce domains are set up on SocketLa","description":"List a server's custom bounce domains and which one is the default. Use for \"Which bounce domains are set up on SocketLabs server 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"domain","description":"Field to sort by, for example domain.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id"],"title":"list_bounce_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_dkim_entries":{"post":{"operationId":"list_dkim_entries","summary":"List a server's DKIM entries with domain, selector and record type (the private key is shown only in truncated form by t","description":"List a server's DKIM entries with domain, selector and record type (the private key is shown only in truncated form by the provider and is not returned here). Use for \"Which DKIM selectors does SocketLabs server 12345 use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"domain","description":"Field to sort by, for example domain.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id"],"title":"list_dkim_entriesArguments","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_tracking_domains":{"post":{"operationId":"list_tracking_domains","summary":"List a server's engagement tracking domains with open, click and unsubscribe tracking switches and encrypted tracking st","description":"List a server's engagement tracking domains with open, click and unsubscribe tracking switches and encrypted tracking status. Use for \"Is click tracking enabled on SocketLabs server 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"domain","description":"Field to sort by, for example domain.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id"],"title":"list_tracking_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/get_delivery_overview":{"post":{"operationId":"get_delivery_overview","summary":"Show daily delivery totals for a server over a date range: queued, sent, delivered, opens, clicks, unsubscribes, failure","description":"Show daily delivery totals for a server over a date range: queued, sent, delivered, opens, clicks, unsubscribes, failures and complaints. Use for \"How many emails did SocketLabs server 12345 deliver between 2026-10-01 and 2026-10-07\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"start_date":{"description":"First day to include, as yyyy-MM-dd.","maxLength":19,"title":"Start Date","type":"string"},"end_date":{"description":"Last day to include, as yyyy-MM-dd; not before start_date.","maxLength":19,"title":"End Date","type":"string"}},"required":["server_id","start_date","end_date"],"title":"get_delivery_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_failures_overview":{"post":{"operationId":"get_failures_overview","summary":"Show daily failure totals for a server over a date range: hard and soft failures, complaints and suppressed messages. Us","description":"Show daily failure totals for a server over a date range: hard and soft failures, complaints and suppressed messages. Use for \"How many emails failed on SocketLabs server 12345 last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"start_date":{"description":"First day to include, as yyyy-MM-dd.","maxLength":19,"title":"Start Date","type":"string"},"end_date":{"description":"Last day to include, as yyyy-MM-dd; not before start_date.","maxLength":19,"title":"End Date","type":"string"}},"required":["server_id","start_date","end_date"],"title":"get_failures_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/list_failed_messages":{"post":{"operationId":"list_failed_messages","summary":"List messages that failed to deliver in a date range with recipient, sender, subject, mailing id and the receiving mail ","description":"List messages that failed to deliver in a date range with recipient, sender, subject, mailing id and the receiving mail server. Use for \"Which messages failed on SocketLabs server 12345 yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"start_date":{"description":"First day to include, as yyyy-MM-dd.","maxLength":19,"title":"Start Date","type":"string"},"end_date":{"description":"Last day to include, as yyyy-MM-dd; not before start_date.","maxLength":19,"title":"End Date","type":"string"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"to","description":"Field to sort by, for example to.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id","start_date","end_date"],"title":"list_failed_messagesArguments","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_messages_by_recipient":{"post":{"operationId":"search_messages_by_recipient","summary":"List the messages sent to one recipient address in a date range with delivery status, last event, opens and clicks. Use ","description":"List the messages sent to one recipient address in a date range with delivery status, last event, opens and clicks. Use for \"What happened to emails sent to jane@example.com through SocketLabs server 12345 this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"to_email_address":{"description":"Recipient email address to look up.","maxLength":200,"title":"To Email Address","type":"string"},"start_date":{"description":"First day to include, as yyyy-MM-dd.","maxLength":19,"title":"Start Date","type":"string"},"end_date":{"description":"Last day to include, as yyyy-MM-dd; not before start_date.","maxLength":19,"title":"End Date","type":"string"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"to","description":"Field to sort by, for example to.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id","to_email_address","start_date","end_date"],"title":"search_messages_by_recipientArguments","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_suppressions":{"post":{"operationId":"search_suppressions","summary":"List addresses on a server's suppression list with the reason and last update, sorted by email address by default. Use f","description":"List addresses on a server's suppression list with the reason and last update, sorted by email address by default. Use for \"Which addresses are suppressed on SocketLabs server 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based page to return; 0 is the first page.","title":"Page Number"},"sort_field":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"emailAddress","description":"Field to sort by, for example emailAddress.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","dsc"],"type":"string"},{"type":"null"}],"default":"dsc","description":"asc or dsc (descending).","title":"Sort Direction"}},"required":["server_id"],"title":"search_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/get_streamscore":{"post":{"operationId":"get_streamscore","summary":"Show a server's StreamScore (sender reputation score) for a day with week-over-week and day-over-day change. Use for \"Wh","description":"Show a server's StreamScore (sender reputation score) for a day with week-over-week and day-over-day change. Use for \"What is the StreamScore of SocketLabs server 12345 today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"},"request_date":{"description":"Day to score, as yyyy-MM-dd.","maxLength":19,"title":"Request Date","type":"string"}},"required":["server_id","request_date"],"title":"get_streamscoreArguments","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_sender_queue_count":{"post":{"operationId":"get_sender_queue_count","summary":"Show how many messages are waiting in a server's sender queue. Use for \"How many emails are queued on SocketLabs server ","description":"Show how many messages are waiting in a server's sender queue. Use for \"How many emails are queued on SocketLabs server 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Your SocketLabs server (Simple Sender) number, for example 12345; shown in the SocketLabs control panel.","minimum":1,"title":"Server Id","type":"integer"}},"required":["server_id"],"title":"get_sender_queue_countArguments","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}}}}