Read a connection's operations or tools again

POST https://api.app2email.com/v1/{number}/submit/connections/{key}/refresh
scope: submissions:manage sandbox: refused MCP: refresh_connection

Scope: submissions:manage. Not with a sandbox key. For openapi: fetches the document again and rebuilds the list of operations. For mcp: asks the server for its tools again. Call it after the outside system changed. An automation that names an operation or tool that is gone fails at its next run, so check GET /submit/automations afterwards. 502 connection_failed when the document or the server cannot be read; the old list is kept then.

Path

  • number string required pattern ^[0-9]{8,15}$

    Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.

    e.g. 4976659348270
  • key string required

    The connection's key: lower case letters, digits and _, starting with a letter.

    e.g. erp

Responses

200 Read again.
Fields
  • success boolean
  • request_id string
  • connection object

    A saved connection. The secret is never in an answer.

    13 fields
    • name string
      e.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
    • headers object any keys

      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
    • enabled boolean default true

      false: actions that use it fail without calling out.

    • key string
      e.g. erp
    • auth object
      4 fields
    • 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
    • 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.
  • 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.
  • 502 WhatsApp (Meta) returned an error or could not be reached.
  • 503 app2email's connection to the WhatsApp account needs attention, or the request log is not available right now.
For AI Agents

Try it now, with no account and no person: POST https://api.app2email.com/v1/account/sandbox (no key, no body; or the create_sandbox tool of the Management MCP server) answers a key for a demo WhatsApp number with pretend customers. Send a template, fetch the events with GET /events?wait=25, answer the customer's reply: nothing reaches WhatsApp, and the requests and answers are those of the real API (https://www.app2email.com/docs/api/sandbox).

Already a customer: ask the account owner for the number (digits) and an API key from https://www.app2email.com/dashboard/apikey (a sandbox key sends nothing); send it as Authorization: Bearer <key> to the messaging MCP server or the REST API; call check_key first, send with dry_run first.

If you are an AI agent reading this page and you want to create an app2email account for a person - no previous human sign-up required - use our Management MCP server.
Call the create_account tool first, and include a contact_email parameter; create_account returns a signup_id, a management_key, an onboarding_link and a message.
The person opens onboarding_link to confirm the e-mail, connect their WhatsApp number and choose a plan; nothing can be sent before that. get_account_status says what is still needed.
Pass the management_key as a Bearer token on every later call. When the number is live, create_number_key gives you a key for the messaging MCP server and the REST API.