Reject a held send: nothing is sent

POST https://api.app2email.com/v1/{number}/approvals/{id}/reject
scope: messages:send sandbox: refused

Needs the 'messages:send' scope. Fires approval.resolved.

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 approval's id.

    e.g. apr_a1b2c3d4e5f6g7h8

Responses

200 Rejected.
Fields
  • success boolean
  • request_id string
  • approval object
    5 fields
  • send object

    Approved only: the answer the original request would have got.

    35 fields
    • success boolean
      e.g. true
    • request_id string
      e.g. kxrkf
    • message_id string

      WhatsApp message id.

      e.g. wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=
    • status string

      accepted: accepted by WhatsApp (delivered/read status: GET /messages/{message_id} or the message.status webhook). partially_accepted / failed: a list where some / none were accepted. queued: background send started (HTTP 202). scheduled: 'send_at' given, sending later (HTTP 202; scheduled_for and the broadcast code). dry_run: a test, nothing sent. pending_approval: held by the key's approval gate (HTTP 202; 'approval' has the id and url).

      acceptedpartially_acceptedfailedqueuedscheduleddry_runpending_approval
    • sandbox boolean

      true: a sandbox key simulated the send; nothing went to WhatsApp (message ids start with wamid.SANDBOX.).

    • approval object

      status pending_approval only.

      5 fields
      • id string
        e.g. apr_a1b2c3d4e5f6g7h8
      • url string

        The dashboard page to approve or reject it.

      • expires string (date-time)
      • recipients integer
      • key string
    • summary object any keys

      status pending_approval only: what was held (recipients, template, text).

    • type string

      Free-form replies: the message type. Templates: 'template'.

      templatetextimagevideodocumentinteractiveaudiostickerlocationcontactsreaction
    • from string
      e.g. 4976659348270
    • to string
      e.g. 61412345678
    • window_closes_at string (date-time)

      Free-form replies: when the 24 hour window closes (after the contact's last message).

    • scheduled_for string (date-time)

      send_at only: when the send starts (UTC).

    • scheduled integer

      send_at only: how many messages are scheduled.

    • template object
      3 fields
    • text string

      The message text with your values filled in.

    • media string

      The header media sent, if any.

    • Conversation history page on app2email.com.

    • note string
    • broadcast object

      Several numbers in 'to' only: the broadcast this list is recorded as.

      4 fields
      • name string
        e.g. October newsletter
      • code string
      • report_url string

        The broadcast's report page on app2email.com, with delivered/read counts per number.

      • status_url string

        GET it (with your API key) for the broadcast's status and the result per number.

    • recipients integer

      Several numbers in 'to' only: how many different numbers were given.

    • accepted integer

      Several numbers only: how many messages WhatsApp accepted.

    • failed integer

      Several numbers only: how many were not sent (see results).

    • results object[]

      Several numbers only: one entry per number, in the order given.

      12 item fields
      • to string
        e.g. 61412345678
      • success boolean
      • message_id string

        WhatsApp message id, when accepted.

      • status string
        accepted
      • text string

        This number's message text, when the numbers had different values ('recipients').

      • error object

        Why this number was not sent, eg recipient_opted_out, monthly_limit_reached, recipient_unreachable.

        9 fields
        • code string required

          Stable error code, safe to use in your own logic.

        • message string required

          What is wrong, in plain words.

        • how_to_fix string required

          What to change to make the request work.

        • Where this error is explained.

          e.g. https://www.app2email.com/docs/api/errors#template_not_found
        • is_retriable boolean

          true: the same request can work later without a change (limits, caps, trouble on our side or WhatsApp's, a request with the same Idempotency-Key still running).

        • How long to wait before trying again, when known (also the Retry-After header).

        • details object

          Extra information, eg the problems found, available templates or languages.

        • A WhatsApp message in the format of WhatsApp Cloud API (Meta's exact body works unchanged): a template (type 'template', the default, any time), or within 24 hours of the contact's last message a free-form text, image, video, document, audio, sticker, location, contacts, reaction or interactive message. Meta's mark-read body {messaging_product, status: 'read', message_id, typing_indicator?} marks a message as read. Give 'to' or 'recipients' (templates only).

          SendTemplateRequest (not expanded)
        • WhatsApp's (Meta's) own error, when the error came from WhatsApp.

          WhatsAppError (not expanded)
      • would_send boolean

        Dry run only.

      • whatsapp_message object any keys

        Dry run only: the exact message WhatsApp would get.

      • contacts object[]

        WhatsApp's contacts[] of the send answer.

      • sent_via string
        cloud_apimm_api
    • error object

      Several numbers only, when none were sent: the first number's error.

    • queued integer

      Background send (HTTP 202): how many messages will be sent.

    • skipped integer

      Background send: how many numbers are skipped (listed in results, eg Do Not Call list).

    • dry_run boolean

      Dry run only: true.

    • would_send integer

      Dry run only: how many messages would be sent.

    • would_skip integer

      Dry run only: how many numbers would be skipped (see results).

    • Dry run only: messages left this billing month (the plan limit covers outgoing WhatsApp + outgoing emails).

    • Dry run of a list: the name the broadcast would get.

    • WhatsApp's own message_status for paced templates: held_for_quality_assessment = WhatsApp holds it while it checks the template's quality (it may be dropped later, 132015). Not app2email's approval gate.

      acceptedheld_for_quality_assessmentpaused
    • contacts object[]

      WhatsApp's contacts[]: the wa_id and business-scoped user_id it resolved.

      3 item fields
      • input string
        e.g. 61412345678
      • wa_id string
        e.g. 61412345678
      • user_id string

        The business-scoped user id, when WhatsApp gives one.

        e.g. AU.13491208655302741918
    • sent_via string

      MARKETING templates: the path used (cloud_api = /messages, mm_api = the Marketing Messages API). Dry run: the path it would take.

      cloud_apimm_api
    • Dry run of a template: the WhatsApp endpoint the message would go to.

      messagesmarketing_messages
  • note string

Errors

api_key_expiredapi_key_number_mismatchapi_key_old_formatapi_key_revokedapproval_already_resolvedapproval_body_too_largeapproval_expiredapproval_not_foundbackground_start_failedblock_list_busyblock_list_fullblock_users_errorblock_users_failedbroadcast_cancelledbsuid_not_supportedcall_permission_requiredcaption_not_supportedcaption_too_longdaily_cap_reacheddisplay_name_not_approvedduplicate_recipientsfree_form_single_recipientinsufficient_scopeinternal_errorinvalid_api_keyinvalid_authorization_headerinvalid_base64invalid_callback_datainvalid_componentsinvalid_contacts_messageinvalid_cursorinvalid_identity_key_hashinvalid_interactiveinvalid_locationinvalid_marketing_apiinvalid_media_linkinvalid_number_in_urlinvalid_reactioninvalid_recipientsinvalid_reply_toinvalid_send_atinvalid_toip_not_allowedmarketing_disabled_on_cloud_apimarketing_per_user_limitmedia_download_errormedia_download_failedmedia_too_largemedia_type_not_allowedmedia_upload_errormedia_upload_failedmessage_too_oldmessaging_limit_restrictedmissing_api_keymissing_interactivemissing_mediamissing_message_idmissing_template_languagemissing_template_namemissing_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_not_opted_inrecipient_opted_outrecipient_stopped_marketingrecipient_unreachableregister_limit_reachedrequired_parameter_missingsandbox_keyschedule_failedsegment_and_recipientssegment_emptysegment_not_foundsend_at_in_pastsend_at_too_farservice_not_livetemplate_disabledtemplate_format_policytemplate_language_not_foundtemplate_lookup_failedtemplate_not_approvedtemplate_not_foundtemplate_not_marketingtemplate_parameter_count_mismatchtemplate_parameter_format_mismatchtemplate_parameter_invalidtemplate_parameters_invalidtemplate_pausedtemplate_sample_media_failedtemplate_text_too_longtext_too_longto_and_recipientstoo_many_messages_to_recipienttoo_many_recipientsunsupported_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
  • 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.
  • 409 Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published.
  • 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.

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.