Send a WhatsApp message: template, or free-form reply

POST https://api.app2email.com/v1/{number}/messages
scope: messages:send sandbox: simulated Idempotency-Key MCP: send_template

Sends one approved template to one recipient, or to several when to lists several numbers (or recipients gives each number its own values). The parameters are checked against the template before sending; on a mismatch the error includes a complete, correct example_request for that template. Nothing is sent when the request itself is invalid. dry_run checks without sending; background answers 202 and sends after; send_at schedules it (202, status scheduled). type text, image, video, document or interactive sends a free-form message to one contact within 24 hours of the contact's last message (422 outside_24h_window otherwise). segment sends a template to a saved segment's contacts. A business-scoped user id works wherever a number does. Also audio, sticker, location, contacts, reaction and the newer interactive kinds; template carousels, limited-time offers, catalog, MPM, SPM, flow and OTP buttons. callback_data comes back in message.status. MARKETING templates follow marketing_api / messages.marketing_route (sent_via in the answer).

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

Headers

  • Idempotency-Key string max 255 chars

    A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.

    e.g. order-1234-shipped

Body application/json required

  • Always 'whatsapp'.

    whatsapp
  • Always 'individual'.

    individual
  • to string

    Recipient's WhatsApp number with country code. Digits only is best (spaces, '+', '-' are removed). Several recipients: separate the numbers with commas, eg "61412345678,61498765432" (semicolons and new lines work too), or send a JSON array of numbers. Each number gets its own message, and the response lists the result per number in 'results'. A free-form message (not 'template') goes to one number. A business-scoped user id (eg 61.AbC123, from from_user_id) is accepted as it is.

    e.g. 61412345678
  • recipient string

    Instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'.

    e.g. 61.AbC123xyz
  • segment string

    app2email only, instead of 'to' / 'recipients': the id or name of a saved segment (GET /segments). Templates only. Each contact's named template parameters without a value are filled from its custom_fields ('name' from the contact's name). Recorded as a broadcast.

    e.g. VIP, consented
  • type string default template

    'template' (default): an approved template. Otherwise a free-form message within the 24 hour window; the field of the same name holds it. Left out with status 'read': mark as read.

    templatetextimagevideodocumentinteractiveaudiostickerlocationcontactsreaction
  • interactive object

    type 'interactive': reply buttons, a list, or a URL button.

    5 fields
    • type string required
      buttonlistcta_urlcarousellocation_request_messagerequest_contact_infoflowproductproduct_listcatalog_messagecall_permission_requestvoice_calladdress_messageorder_detailsorder_status
    • header object any keys
      e.g. {"type":"text","text":"Booking"}
    • body object
      1 fields
      • text string required max 1024 chars
        e.g. Confirm your booking for Friday 10:00?
    • footer object
      1 fields
      • text string max 60 chars
    • action object required any keys
      e.g. {"buttons":[{"type":"reply","reply":{"id":"yes","title":"Confirm"}},{"type":"re…
  • template object
    3 fields
    • name string required

      Exact name of an APPROVED template.

      e.g. order_update
    • language object

      Required when the template exists in more than one language.

      1 fields
      • code string required

        Template language code, eg 'en', 'en_US', 'nl'.

        e.g. en
    • components object[]

      Values for the template's placeholders and media. Leave out for templates without parameters.

      5 item fields
      • type string required
        headerbodybuttoncarousellimited_time_offer
      • sub_type string

        Buttons only.

        urlquick_replycopy_codeflowcatalogmpmspmorder_details
      • index string

        Buttons only: position of the button in the template, starting at 0.

        e.g. 0
      • parameters object[]
        14 item fields
        • type string required
          textimagevideodocumentlocationcurrencydate_timepayloadcoupon_codeactionproductlimited_time_offer
        • For templates with NAMED placeholders, eg 'first_name' for {{first_name}}.

        • text string

          type 'text'. No new lines, tabs or more than 4 spaces in a row.

        • image object

          Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.

          5 fields
          • data string (byte)

            The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

          • id string

            A media id already uploaded to WhatsApp for this number.

          • filename string

            Shown to the recipient for documents. Also helps detect the file type.

            e.g. invoice.pdf
          • mime_type string

            The type is detected from the file where possible.

            e.g. application/pdf
        • video object

          Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.

          5 fields
          • data string (byte)

            The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

          • id string

            A media id already uploaded to WhatsApp for this number.

          • filename string

            Shown to the recipient for documents. Also helps detect the file type.

            e.g. invoice.pdf
          • mime_type string

            The type is detected from the file where possible.

            e.g. application/pdf
        • document object

          Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.

          5 fields
          • data string (byte)

            The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

          • id string

            A media id already uploaded to WhatsApp for this number.

          • filename string

            Shown to the recipient for documents. Also helps detect the file type.

            e.g. invoice.pdf
          • mime_type string

            The type is detected from the file where possible.

            e.g. application/pdf
        • location object
          4 fields
        • currency object
          3 fields
        • date_time object
          1 fields
        • payload string

          type 'payload': quick reply button payload.

        • coupon_code string

          type 'coupon_code': copy code button value.

        • action object any keys

          type 'action': flow / catalog button data, as WhatsApp Cloud API.

        • product object

          type 'product': a product header.

          2 fields
        • type 'limited_time_offer': when the offer ends (ms since 1970).

          1 fields
      • cards object[]

        type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.

        2 item fields
  • text object

    type 'text': the message.

    2 fields
    • body string required

      The text. Up to 4096 characters.

      e.g. Thanks, it arrives on Friday.
    • preview_url boolean default false

      true: show a preview of a link in the text.

  • image object

    type 'image': link, data+filename or id, and an optional caption.

    6 fields
    • data string (byte)

      The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

    • id string

      A media id from POST /media (or uploaded to WhatsApp for this number).

    • filename string

      Needed with 'data' for documents.

      e.g. invoice.pdf
    • mime_type string

      The type is detected from the file where possible.

      e.g. application/pdf
    • caption string max 1024 chars

      Optional text under the image, video or document.

      e.g. Your parcel
  • video object

    type 'video': link, data+filename or id, and an optional caption.

    6 fields
    • data string (byte)

      The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

    • id string

      A media id from POST /media (or uploaded to WhatsApp for this number).

    • filename string

      Needed with 'data' for documents.

      e.g. invoice.pdf
    • mime_type string

      The type is detected from the file where possible.

      e.g. application/pdf
    • caption string max 1024 chars

      Optional text under the image, video or document.

      e.g. Your parcel
  • document object

    type 'document': link, data+filename or id, and an optional caption.

    6 fields
    • data string (byte)

      The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

    • id string

      A media id from POST /media (or uploaded to WhatsApp for this number).

    • filename string

      Needed with 'data' for documents.

      e.g. invoice.pdf
    • mime_type string

      The type is detected from the file where possible.

      e.g. application/pdf
    • caption string max 1024 chars

      Optional text under the image, video or document.

      e.g. Your parcel
  • reply_to string

    Free-form only: the message_id of one of the contact's messages, quoted by this one. Meta's 'context': {"message_id": ...} works too.

    e.g. wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=
  • send_at string (date-time)

    Templates only: send later. ISO 8601 with a time zone ('Z' or '+11:00'), 1 minute to 29 days ahead. The answer is HTTP 202 with status 'scheduled'.

    e.g. 2026-11-02T09:00:00+11:00
  • campaign_name string max 100 chars

    app2email only. Several numbers in 'to' (or 'recipients'): the name of the broadcast this list is recorded as (Activity Log under Broadcasts). Default "API: <template name>". Not used for one number.

    e.g. October newsletter
  • recipients object[]

    app2email only, instead of 'to': each number with its own values. Each entry's components replace the shared template.components of the same type (a button: the same index). Every number is checked before anything is sent.

    3 item fields
    • to string required

      One number, with country code.

      e.g. 61412345678
    • components object[]

      Only what differs for this number, eg its body values. The rest comes from template.components.

      5 item fields
      • type string required
        headerbodybuttoncarousellimited_time_offer
      • sub_type string

        Buttons only.

        urlquick_replycopy_codeflowcatalogmpmspmorder_details
      • index string

        Buttons only: position of the button in the template, starting at 0.

        e.g. 0
      • parameters object[]
        14 item fields
        • type string required
          textimagevideodocumentlocationcurrencydate_timepayloadcoupon_codeactionproductlimited_time_offer
        • For templates with NAMED placeholders, eg 'first_name' for {{first_name}}.

        • text string

          type 'text'. No new lines, tabs or more than 4 spaces in a row.

        • image object

          Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.

          5 fields
          • data string (byte)

            The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

          • id string

            A media id already uploaded to WhatsApp for this number.

          • filename string

            Shown to the recipient for documents. Also helps detect the file type.

            e.g. invoice.pdf
          • mime_type string

            The type is detected from the file where possible.

            e.g. application/pdf
        • video object

          Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.

          5 fields
          • data string (byte)

            The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

          • id string

            A media id already uploaded to WhatsApp for this number.

          • filename string

            Shown to the recipient for documents. Also helps detect the file type.

            e.g. invoice.pdf
          • mime_type string

            The type is detected from the file where possible.

            e.g. application/pdf
        • document object

          Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.

          5 fields
          • data string (byte)

            The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.

          • id string

            A media id already uploaded to WhatsApp for this number.

          • filename string

            Shown to the recipient for documents. Also helps detect the file type.

            e.g. invoice.pdf
          • mime_type string

            The type is detected from the file where possible.

            e.g. application/pdf
        • location object
          4 fields
        • currency object
          3 fields
        • date_time object
          1 fields
        • payload string

          type 'payload': quick reply button payload.

        • coupon_code string

          type 'coupon_code': copy code button value.

        • action object any keys

          type 'action': flow / catalog button data, as WhatsApp Cloud API.

        • product object

          type 'product': a product header.

          2 fields
        • type 'limited_time_offer': when the offer ends (ms since 1970).

          1 fields
      • cards object[]

        type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.

        2 item fields
    • recipient_identity_key_hash string max 200 chars

      This contact's identity_key_hash (see the request's).

  • dry_run boolean default false

    app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything.

  • background boolean default false

    app2email only. true: answer HTTP 202 once everything is checked and the media uploaded, then send. Progress: broadcast.status_url (GET /v1/{number}/broadcasts/{code}) or the broadcast.completed webhook event.

  • audio object

    type 'audio'.

    6 fields
    • data string (byte)

      The file, base64 encoded.

    • id string

      A media id from POST /media.

    • filename string
    • mime_type string
    • voice boolean

      true: a voice message (play button, transcript). Ogg with the OPUS codec only; app2email does not convert.

  • sticker object

    type 'sticker'.

    5 fields
    • data string (byte)

      The file, base64 encoded.

    • id string

      A media id from POST /media.

    • filename string
    • mime_type string
  • location object

    type 'location'.

    4 fields
    • latitude number required -90–90
      e.g. -33.8568
    • longitude number required -180–180
      e.g. 151.2153
    • name string
      e.g. Sydney Opera House
    • address string
      e.g. Bennelong Point, Sydney NSW 2000
  • contacts object[]

    type 'contacts': 1 to 20 cards.

    7 item fields
  • reaction object

    type 'reaction'.

    2 fields
    • message_id string required

      A message the contact sent, up to 30 days old.

      e.g. wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=
    • emoji string required

      One emoji. "" removes your reaction.

      e.g. 👍
  • context object

    Meta's form of reply_to.

    1 fields
  • callback_data string max 512 chars

    Sent to WhatsApp as biz_opaque_callback_data; back as data.callback_data in this message's message.status events. Meta's own field name works too.

    e.g. order-1234
  • recipient_identity_key_hash string max 200 chars

    One recipient (per number: in recipients[]): delivered only while the contact's identity key has this hash (message.received data.identity_key_hash); else message.failed, 137000 recipient_identity_changed. Needs PUT /settings/identity-check.

    e.g. DF2lS5v2W6x=
  • MARKETING templates: the path for this send (true = mm_api, false = cloud_api). Default: the number's setting messages.marketing_route (auto).

    autocloud_apimm_api
  • Marketing Messages API only: STRICT = no fallback to the Cloud API. Default CLOUD_API_FALLBACK.

    CLOUD_API_FALLBACKSTRICT
  • Marketing Messages API only: share read and click activity with Meta for this message.

  • status string

    Meta's mark-read body: 'read' with message_id (no type).

    read
  • message_id string

    Meta's mark-read body: the received message.

  • Meta's mark-read body: also show the typing indicator.

    1 fields

Responses

200 Accepted by WhatsApp (all numbers, when several were given). A dry run also answers 200. A free-form message answers 200 too. A sandbox key answers 200 with sandbox: true.
Headers
  • true when this is the stored answer of an earlier request with the same Idempotency-Key.

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 369 values

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

        account_deactivatedaccount_not_confirmedaccount_service_erroraccount_service_unavailableapi_key_expiredapi_key_number_mismatchapi_key_old_formatapi_key_revokedapproval_already_resolvedapproval_body_too_largeapproval_expiredapproval_not_foundautomation_not_foundbackground_start_failedblock_list_busyblock_list_fullblock_not_foundblock_users_errorblock_users_failedbooking_cancelledbooking_not_enabledbooking_not_foundbooking_slot_takenbroadcast_cancelledbroadcast_not_cancellablebroadcast_not_foundbsuid_not_supportedcall_permission_requiredcaption_not_supportedcaption_too_longcatcher_not_foundclient_existsclient_not_editableclient_not_foundconnection_failedconnection_in_useconnection_not_foundcontact_book_errorcontact_not_foundconversation_not_found
      • 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 any keys

        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).

        Fields: as the request body
      • WhatsApp's (Meta's) own error, when the error came from WhatsApp.

        5 fields
    • would_send boolean

      Dry run only.

    • whatsapp_message object any keys

      Dry run only: the exact message WhatsApp would get.

    • contacts object[]
      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
      cloud_apimm_api
  • error object

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

    Fields: as results.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
202 "background": true - checked, and sending has started (progress: broadcast.status_url). Or "send_at" - status scheduled, sent at scheduled_for (cancel with POST /broadcasts/{code}/cancel). Or status pending_approval: held by the key's approval gate until a person approves it (approval.url). The example is the background answer.
Fields as 200
207 Several numbers: some were accepted, some not. 'results' has the outcome per number.
Fields as 200

Errors

api_key_expiredapi_key_number_mismatchapi_key_old_formatapi_key_revokedapproval_body_too_largebackground_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_recipientidempotency_key_reusedidempotency_request_in_progressidempotency_request_interruptedinsufficient_scopeinternal_errorinvalid_api_keyinvalid_authorization_headerinvalid_base64invalid_callback_datainvalid_componentsinvalid_contacts_messageinvalid_cursorinvalid_idempotency_keyinvalid_identity_key_hashinvalid_interactiveinvalid_jsoninvalid_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_reachedrequest_too_largerequired_parameter_missingschedule_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_content_typeunsupported_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.
  • 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.
  • 413 The request or the media file is too large.
  • 415 The body is not JSON.
  • 422 The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window).
  • 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.

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.