{"openapi":"3.1.0","info":{"title":"Elastic Email (BYOK) API","version":"0.1.0","description":"Elastic Email (BYOK) lets an AI assistant read your own Elastic Email data through the Elastic Email API with a key you supply (API key (give it only read access levels)). Read-only: 12 tools (list_contacts, get_contact, list_lists, list_list_contacts, list_segments, list_campaigns, get_campaign, list_events, get_statistics, list_campaign_statistics, list_bounces, list_domains). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-elasticemail.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-elasticemail/docs"},"termsOfService":"https://connectorbay.com/byok-elasticemail/terms"},"servers":[{"url":"https://byok-elasticemail.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-elasticemail/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/list_contacts":{"post":{"operationId":"list_contacts","summary":"List contacts with email, status, name, source, dates and engagement totals (sent, opened, clicked, failed). Use for \"Wh","description":"List contacts with email, status, name, source, dates and engagement totals (sent, opened, clicked, failed). Use for \"Who are my Elastic Email contacts and how engaged are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_contactsArguments","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_contact":{"post":{"operationId":"get_contact","summary":"Get one contact by email address with status, name, source, dates and engagement totals. Use for \"What is the status of ","description":"Get one contact by email address with status, name, source, dates and engagement totals. Use for \"What is the status of ada@example.com in Elastic Email\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"description":"The contact's email address, for example 'ada@example.com'.","maxLength":254,"title":"Email","type":"string"}},"required":["email"],"title":"get_contactArguments","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_lists":{"post":{"operationId":"list_lists","summary":"List contact lists with name, public id, date added and whether unsubscribing is allowed. Use for \"What contact lists do","description":"List contact lists with name, public id, date added and whether unsubscribing is allowed. Use for \"What contact lists do I have in Elastic Email\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_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_list_contacts":{"post":{"operationId":"list_list_contacts","summary":"List the contacts of one list, by list name, with email, status, name and engagement totals. Use for \"Who is on my Elast","description":"List the contacts of one list, by list name, with email, status, name and engagement totals. Use for \"Who is on my Elastic Email list called Newsletter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"listname":{"description":"Name of the list (as shown by list_lists), for example 'Newsletter'.","maxLength":200,"title":"Listname","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"required":["listname"],"title":"list_list_contactsArguments","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_segments":{"post":{"operationId":"list_segments","summary":"List segments with name and the rule that defines them. Use for \"What segments do I have in Elastic Email\".","description":"List segments with name and the rule that defines them. Use for \"What segments do I have in Elastic Email\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_segmentsArguments","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 with name, status, target lists and segments, tracking options and schedule. Optionally search by name. U","description":"List campaigns with name, status, target lists and segments, tracking options and schedule. Optionally search by name. Use for \"What Elastic Email campaigns have I run\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only campaigns whose name contains this text.","title":"Search"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"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 by name with status, recipients, tracking options, schedule and content settings (sender, subject, temp","description":"Get one campaign by name with status, recipients, tracking options, schedule and content settings (sender, subject, template name). Use for \"Show my Elastic Email campaign January news\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Campaign name, for example 'January news'.","maxLength":200,"title":"Name","type":"string"}},"required":["name"],"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/list_events":{"post":{"operationId":"list_events","summary":"List email events (sent, opened, clicked, bounced, complained, unsubscribed) with recipient, subject, type, time and cha","description":"List email events (sent, opened, clicked, bounced, complained, unsubscribed) with recipient, subject, type, time and channel, for a period. Use for \"Which emails bounced in Elastic Email this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period, written YYYY-MM-DDThh:mm:ss (for example 2026-01-01T00:00:00).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period, written YYYY-MM-DDThh:mm:ss.","title":"Date To"},"order_by":{"anyOf":[{"enum":["DateDescending","DateAscending"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by DateDescending or DateAscending.","title":"Order By"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many events to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_eventsArguments","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_statistics":{"post":{"operationId":"get_statistics","summary":"Get overall sending statistics for a period: recipients, delivered, bounced, opened, clicked, unsubscribed, complaints a","description":"Get overall sending statistics for a period: recipients, delivered, bounced, opened, clicked, unsubscribed, complaints and not delivered. Use for \"How many emails did I deliver through Elastic Email this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"description":"Start of the period, written YYYY-MM-DDThh:mm:ss.","maxLength":19,"title":"Date From","type":"string"},"date_to":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period, written YYYY-MM-DDThh:mm:ss (default now).","title":"Date To"}},"required":["date_from"],"title":"get_statisticsArguments","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_campaign_statistics":{"post":{"operationId":"list_campaign_statistics","summary":"List statistics per campaign or channel: recipients, delivered, bounced, opened, clicked, unsubscribed and complaints. U","description":"List statistics per campaign or channel: recipients, delivered, bounced, opened, clicked, unsubscribed and complaints. Use for \"Which Elastic Email campaign got the most opens\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_campaign_statisticsArguments","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_bounces":{"post":{"operationId":"list_bounces","summary":"List addresses suppressed because they bounced, with error message, error code and date. Optionally search by text. Use ","description":"List addresses suppressed because they bounced, with error message, error code and date. Optionally search by text. Use for \"Which addresses bounced on Elastic Email\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text fragment to search for in the address.","title":"Search"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_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/list_domains":{"post":{"operationId":"list_domains","summary":"List sending domains with SPF, DKIM, MX and DMARC verification flags, tracking status and whether each is the default. U","description":"List sending domains with SPF, DKIM, MX and DMARC verification flags, tracking status and whether each is the default. Use for \"Are my Elastic Email sending domains verified\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_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}}}}