Create or change a connection (HTTP, OpenAPI or MCP)
https://api.app2email.com/v1/{number}/submit/connections/{key} Scope: submissions:manage. Not with a sandbox key. Makes the connection when the key is new (name and kind are needed then), else changes it: a body without kind changes only the keys it names. kind http: a base address and a sign-in. openapi: also spec_url (or spec), an OpenAPI 3 document in JSON. mcp: base_url is the MCP server's address. auth.secret is write-only: it is stored encrypted, never returned, and kept when a later PUT leaves it out (a changed address needs it again). Addresses must be https and public. Saving does not call the outside system: a posted spec is read into operations at once, a spec_url and an MCP server's tools are read by POST /submit/connections/{key}/refresh. Next: POST /submit/connections/{key}/test, then refresh (openapi, mcp) and GET /submit/connections/{key}/functions to see what an action can call. A number has at most 30 connections.
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270 -
The connection's key: lower case letters, digits and _, starting with a letter.
e.g.erp
Body application/json required
- name stringe.g.
ERP - kind string
http: A base address and a sign-in. An http action names the method, path, query, headers and JSON body.openapi: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters.mcp: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments.httpopenapimcp - base_url string
https only. http: the base every path is added to. openapi: the API's base; left empty, the document's first server is used. mcp: the server's address.
e.g.https://erp.example.com/api -
Up to 5 fixed headers sent with every call. Not secret: they are shown again.
e.g.{"X-Tenant":"acme"} - spec_url string
openapi only: where the OpenAPI document (JSON) is read from.
e.g.https://erp.example.com/openapi.json -
false: actions that use it fail without calling out.
- auth object
4 fields
-
none: No sign-in.bearer: Authorization: Bearer <secret>.header: The header called name carries the secret.basic: Basic sign-in with username and the secret as the password.query: The query parameter called name carries the secret.nonebearerheaderbasicquery - name string
header: the header's name. query: the parameter's name.
- username string
basic only.
- secret string
The token, key or password. Write-only: never shown again. Left out: the stored one is kept.
-
-
openapi only: the OpenAPI document itself, posted once instead of spec_url.
Responses
Fields
- success boolean
- request_id string
- connection object
A saved connection. The secret is never in an answer.
13 fields
- name stringe.g.
ERP - kind string
http: A base address and a sign-in. An http action names the method, path, query, headers and JSON body.openapi: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters.mcp: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments.httpopenapimcp - base_url string
https only. http: the base every path is added to. openapi: the API's base; left empty, the document's first server is used. mcp: the server's address.
e.g.https://erp.example.com/api -
Up to 5 fixed headers sent with every call. Not secret: they are shown again.
e.g.{"X-Tenant":"acme"} - spec_url string
openapi only: where the OpenAPI document (JSON) is read from.
e.g.https://erp.example.com/openapi.json -
false: actions that use it fail without calling out.
- key stringe.g.
erp - auth object
4 fields
- type string
nonebearerheaderbasicquery - name string
- username string
- has_secret boolean
A secret is stored. It is never returned.
- functions_count integer
openapi, mcp: how many operations or tools are known.
- functions_at string (date-time) | null
When they were last read.
- last_ok string (date-time) | null
The last call or test that worked.
- last_error string
- used_by string[]
The names of the automations that use it.
- functions object[]
After a refresh.
6 item fields
- id string
openapi: the operationId (or method and path made into a name). mcp: the tool's name. What an action's operation or tool takes.
e.g.createTicket - title string
- method string
openapi only.
- path string
openapi only.
- params object[]
5 item fields
- name string
- in string
Where it goes. mcp arguments are all body.
- type string
- required boolean
- description string
- has_body boolean
The operation takes a JSON body.
Errors
- 400 The request is malformed (missing or invalid fields, query parameters or times).
- 401 Missing, invalid, revoked or expired API key.
- 403 The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account.
- 404 The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found.
- 415 The body is not JSON.
- 429 A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait.
- 500 Unexpected error on app2email's side.
- 503 app2email's connection to the WhatsApp account needs attention, or the request log is not available right now.