{"openapi":"3.1.0","info":{"title":"Emma (BYOK) API","version":"0.1.0","description":"Emma (BYOK) lets an AI assistant read your own Emma data through the Emma API with a key you supply (Emma public API key). Read-only: 12 tools (list_groups, get_group, list_mailings, get_mailing, list_members, get_member_by_email, list_fields, get_response_summary, get_mailing_response, list_searches, list_automation_workflows, list_signup_forms). The BYOK key travels with each request, is used...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-emma.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-emma/docs"},"termsOfService":"https://connectorbay.com/byok-emma/terms"},"servers":[{"url":"https://byok-emma.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-emma/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_groups":{"post":{"operationId":"list_groups","summary":"List the audience groups of the account with active, opted-out and error member counts. Use for \"Which Emma audience gro","description":"List the audience groups of the account with active, opted-out and error member counts. Use for \"Which Emma audience groups do I have and how many active members are in each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"group_types":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated types: g (group, default), t (test), h (hidden) or all.","title":"Group Types"}},"required":["account_id"],"title":"list_groupsArguments","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_group":{"post":{"operationId":"get_group","summary":"Get one audience group with its member counts. Use for \"How many active members does Emma group 150 have\".","description":"Get one audience group with its member counts. Use for \"How many active members does Emma group 150 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"member_group_id":{"description":"Numeric group id.","title":"Member Group Id","type":"integer"}},"required":["account_id","member_group_id"],"title":"get_groupArguments","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_mailings":{"post":{"operationId":"list_mailings","summary":"List mailings (campaigns) with name, subject, sender, status, recipient count and send times. Defaults to standard and t","description":"List mailings (campaigns) with name, subject, sender, status, recipient count and send times. Defaults to standard and test mailings in any status. Use for \"Which Emma mailings have been sent\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"mailing_types":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated types: m standard, t test, r trigger, s subject split test, c content split test (default m,t).","title":"Mailing Types"},"mailing_statuses":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses: p pending, a paused, i injecting, s sending, x canceled, c complete, w waiting, u unapproved, f failed.","title":"Mailing Statuses"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include archived mailings.","title":"Include Archived"},"is_scheduled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for mailings that have a scheduled time.","title":"Is Scheduled"}},"required":["account_id"],"title":"list_mailingsArguments","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_mailing":{"post":{"operationId":"get_mailing","summary":"Get one mailing's name, subject, sender, status, recipient count and send times. Use for \"Show Emma mailing 200\".","description":"Get one mailing's name, subject, sender, status, recipient count and send times. Use for \"Show Emma mailing 200\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"mailing_id":{"description":"Numeric mailing id.","title":"Mailing Id","type":"integer"}},"required":["account_id","mailing_id"],"title":"get_mailingArguments","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_members":{"post":{"operationId":"list_members","summary":"List audience members with email, status, custom fields, sign-up date and bounce count. Use start and end to page. Use f","description":"List audience members with email, status, custom fields, sign-up date and bounce count. Use start and end to page. Use for \"Show the first members of my Emma audience\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"start":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based index of the first item, for paging (documented examples use start=0&end=2).","title":"Start"},"end":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based index to stop at, for paging; pair with start.","title":"End"},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include deleted members.","title":"Deleted"},"deleted_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only deleted members.","title":"Deleted Only"},"exclude_fields":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only the base attributes and leave out custom fields.","title":"Exclude Fields"}},"required":["account_id"],"title":"list_membersArguments","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_member_by_email":{"post":{"operationId":"get_member_by_email","summary":"Look up one audience member by email address. Use for \"Is tony@example.com in my Emma audience and what is their status\"","description":"Look up one audience member by email address. Use for \"Is tony@example.com in my Emma audience and what is their status\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"email":{"description":"Member email address.","maxLength":200,"title":"Email","type":"string"}},"required":["account_id","email"],"title":"get_member_by_emailArguments","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_fields":{"post":{"operationId":"list_fields","summary":"List the custom member fields defined in the account with type and display name. Use for \"What custom fields does my Emm","description":"List the custom member fields defined in the account with type and display name. Use for \"What custom fields does my Emma audience have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include deleted fields.","title":"Deleted"}},"required":["account_id"],"title":"list_fieldsArguments","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_response_summary":{"post":{"operationId":"get_response_summary","summary":"Get a month-by-month summary of sends, deliveries, bounces, opens, clicks, forwards, opt-outs and sign-ups for the whole","description":"Get a month-by-month summary of sends, deliveries, bounces, opens, clicks, forwards, opt-outs and sign-ups for the whole account. Use for \"How did my Emma email performance look month by month this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"range":{"anyOf":[{"maxLength":21,"type":"string"},{"type":"null"}],"default":null,"description":"Date range as two YYYY-MM-DD dates joined by a tilde, for example 2026-01-01~2026-09-30.","title":"Range"},"include_deleted":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Pass 1 to include archived mailings.","title":"Include Deleted"}},"required":["account_id"],"title":"get_response_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_mailing_response":{"post":{"operationId":"get_mailing_response","summary":"Get the response numbers of one mailing: recipients, sent, delivered, bounced, opened, clicked, forwarded, opt-outs, sig","description":"Get the response numbers of one mailing: recipients, sent, delivered, bounced, opened, clicked, forwarded, opt-outs, sign-ups and ecommerce orders. Use for \"How did Emma mailing 200 perform\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"mailing_id":{"description":"Numeric mailing id.","title":"Mailing Id","type":"integer"}},"required":["account_id","mailing_id"],"title":"get_mailing_responseArguments","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_searches":{"post":{"operationId":"list_searches","summary":"List saved member searches (segments) with criteria, active count and last run time. Use for \"Which saved segments do I ","description":"List saved member searches (segments) with criteria, active count and last run time. Use for \"Which saved segments do I have in Emma\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include deleted searches.","title":"Deleted"}},"required":["account_id"],"title":"list_searchesArguments","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_automation_workflows":{"post":{"operationId":"list_automation_workflows","summary":"List automation workflows with name, status (active, inactive, draft) and dates. Use for \"Which Emma automation workflow","description":"List automation workflows with name, status (active, inactive, draft) and dates. Use for \"Which Emma automation workflows are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"}},"required":["account_id"],"title":"list_automation_workflowsArguments","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_signup_forms":{"post":{"operationId":"list_signup_forms","summary":"List the signup forms of the account. Use for \"Which signup forms does my Emma account have\".","description":"List the signup forms of the account. Use for \"Which signup forms does my Emma account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Emma account id (digits; agency accounts use the sub-account id).","title":"Account Id","type":"integer"}},"required":["account_id"],"title":"list_signup_formsArguments","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}}}}