Run a manual automation on a submission

POST https://api.app2email.com/v1/{number}/submit/submissions/{id}/run
scope: submissions:manage sandbox: refused MCP: run_submission_action

Scope: submissions:manage. Not with a sandbox key. Runs one automation whose trigger is manual on this submission now: the same thing as its button in the inbox. automation_id is one of the submission's actions[].id (GET /submit/submissions/{id}); the automation must be switched on and belong to the submission's form (400 invalid_automation otherwise). The automation's conditions are still checked. The answer is the run with every step: what was sent to an outside system and what came back. A step that fails is inside the run (steps[].ok false, status failed), not an error of this call; when the server is busy the run is queued (status waiting) and shows in GET /submit/runs. Whatever the actions do is real: replies are sent, stages change, systems are called.

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
  • id string required

    The submission's id, or its reference (MR-7Q3M2A).

    e.g. MR-7Q3M2A

Body application/json required

  • automation_id integer required

    A manual automation of the submission's form: one of the submission's actions[].id.

    e.g. 31

Responses

200 The run.
Fields
  • success boolean
  • request_id string
  • run object

    One run of an automation on one submission, with every step.

    13 fields
    • id integer

      0 for a try: it is not stored.

    • automation_id integer
    • automation string

      Its name.

    • submission string

      The submission's reference.

    • trigger string
    • status string

      ok: it ran to the end; an action that did not work without stopping the run (a refused stage, a reply that could not be sent) has ok false in its step and its message in error. failed: an outside call ran out of retries, or failed with on_fail stop. waiting: paused by a wait action, between retries, or queued (due says when it continues). skipped: the conditions did not hold, or the automation or the submission was gone.

      runningokfailedwaitingskipped
    • attempt integer
    • steps object[]
      9 item fields
      • n integer

        The action's number in the automation, counted from 1.

      • type string

        The action type.

      • ok boolean
      • ms integer
      • summary string

        What happened, in words.

      • error string
      • request object any keys

        Outside calls only: method, address and what was sent. Never a secret or a sign-in header.

      • response object any keys

        Outside calls only: status and the first 2,000 characters of the answer.

      • try integer

        Only on a retry of an outside call: 2, 3 or 4.

    • error string
    • test boolean

      true: a try, nothing was changed or sent.

    • created string (date-time)
    • finished string (date-time) | null
    • due string (date-time) | null

Errors

api_key_expiredapi_key_number_mismatchapi_key_old_formatapi_key_revokedapproval_body_too_largeautomation_not_foundblock_list_busyblock_list_fullblock_users_errorblock_users_failedbsuid_not_supportedcall_permission_requiredcaption_not_supportedcaption_too_longdaily_cap_reacheddisplay_name_not_approvedfree_form_single_recipientinsufficient_scopeinternal_errorinvalid_api_keyinvalid_authorization_headerinvalid_automationinvalid_base64invalid_callback_datainvalid_contacts_messageinvalid_cursorinvalid_identity_key_hashinvalid_interactiveinvalid_jsoninvalid_locationinvalid_media_linkinvalid_number_in_urlinvalid_reactioninvalid_reply_toinvalid_toip_not_allowedmarketing_disabled_on_cloud_apimarketing_per_user_limitmedia_download_errormedia_download_failedmedia_too_largemedia_type_not_allowedmedia_upload_errormedia_upload_failedmessaging_limit_restrictedmissing_api_keymissing_interactivemissing_mediamissing_textmonthly_cap_reachedmonthly_limit_reachednumber_already_verifiednumber_not_foundoutside_24h_windowparameter_value_invalidplan_not_allowedrate_limitedreaction_too_oldrecipient_identity_changedrecipient_in_experimentrecipient_is_senderrecipient_not_allowedrecipient_opted_outrecipient_stopped_marketingrecipient_unreachableregister_limit_reachedrequired_parameter_missingsandbox_keyservice_not_livesubmission_not_foundsubmit_not_readytemplate_disabledtemplate_format_policytemplate_not_foundtemplate_not_marketingtemplate_parameter_count_mismatchtemplate_parameter_format_mismatchtemplate_parameter_invalidtemplate_pausedtemplate_text_too_longtext_too_longtoo_many_messages_to_recipientunsupported_message_typeusername_account_not_linkedusername_change_limitusername_not_availableusername_not_eligibleusername_takenvoice_needs_ogg_opuswhatsapp_account_lockedwhatsapp_account_restrictedwhatsapp_connection_problemwhatsapp_errorwhatsapp_maintenancewhatsapp_number_not_registeredwhatsapp_parameter_errorwhatsapp_payment_issuewhatsapp_rate_limitwhatsapp_unavailable
  • 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.

Webhooks it causes

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.