Publish a form to WhatsApp

POST https://api.app2email.com/v1/{number}/submit/forms/{key}/publish
scope: submissions:manage sandbox: refused MCP: publish_form

Scope: submissions:manage. Not with a sandbox key. Builds the WhatsApp form from the saved definition, uploads it to Meta and publishes it. From then on the form's words, POST /submit/forms/{key}/send and the menu open it inside WhatsApp. Call it after creating a form and after every change of its definition. 400 invalid_form when the definition cannot be built into a WhatsApp form (the message says what to change). 409 form_not_published when the form is archived, the number's encryption key is not accepted by WhatsApp yet, or WhatsApp found problems in the generated form (error.details.validation_errors has them). 502 whatsapp_flow_failed when WhatsApp refused a call: try again in a minute. People who still have an older message keep the version it was sent with. A form that is not published still works through its web link.

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 form's key (GET /submit/forms).

    e.g. meter_reading

Responses

200 Published.
Fields
  • success boolean
  • request_id string
  • form object

    A form. GET /submit/forms lists forms without definition and fields; GET /submit/forms/{key} has both.

    15 fields
    • id integer
      e.g. 7
    • key string

      The form's name in the API and in its web address.

      e.g. meter_reading
    • name string
      e.g. Meter reading
    • enabled boolean

      false: its words and links answer nothing new; its submissions stay.

    • archived boolean

      true: hidden from the lists, takes no submissions.

    • position integer
    • definition object

      The working copy. One form only.

      12 fields
      • title string required 1–60 chars

        The form's public name, 1 to 60 characters.

        e.g. Meter reading
      • description string max 300 chars

        Under the title on the web page and in the forms menu, up to 300 characters.

      • prefix string

        2 to 4 letters A-Z that start every reference of this form (MR-7Q3M2A). "" = the settings' default_prefix.

        e.g. MR
      • steps object[] required 1–12 items

        1 to 12 steps, in the order they are asked. One step is one screen; app2email splits a step over several screens by itself when WhatsApp's limits demand it.

        5 item fields
        • key string required

          The step's name: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique among the steps.

          e.g. reading
        • title string required

          The screen's title, 1 to 60 characters (WhatsApp shows the first 30).

          e.g. Your reading
        • text string

          Shown above the fields, up to 500 characters.

        • show_if object

          A rule on fields of EARLIER steps: the step is skipped when it does not hold. null = always.

          e.g. {"all":[{"field":"amount","gt":5000},{"field":"category","in":["plant","vehicle…
          SubmitRule (not expanded)
        • fields array required

          1 to 12 fields. Internal and hidden fields count but show nothing.

      • stages object[] 2–12 items

        2 to 12 stages a submission moves through. The first one is where a new submission starts. At least one of kind open and one of kind done. Left out: New (open), In progress (open), Done (done).

        7 item fields
        • key string required

          The stage's name in the API (the submission's status): a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique in the form.

          e.g. received
        • name string required

          What people see, for example In review. Up to 40 characters.

          e.g. Received
        • kind string required

          open: still being worked on. done: finished well. cancelled: finished without a result. A form needs at least one open and one done stage.

        • color string

          grey, blue, green, amber, red or purple.

        • set_by array

          The roles that may choose this stage: some of owner, admin, manager, agent, viewer. [] = anyone who may change stages. Owners, admins, automations and API keys always may.

        • require_note boolean

          true: a note must come with the move to this stage.

        • message string

          Sent to the submitter when the submission arrives in this stage, up to 1,000 characters, with placeholders ({note} = the note of the change). "" = nothing is sent.

      • who object

        Who may submit.

        3 fields
        • mode string default anyone

          listed: only the numbers below, or contacts with the tag, may submit (a form for field staff). listed needs at least one number or a tag.

          anyonelisted
        • numbers string[]

          Up to 500 numbers, digits only with country code (6 to 20 digits).

        • tag string max 40 chars

          A contact tag: contacts carrying it may submit.

      • trigger object

        The message that opens the form on WhatsApp, and the words that send it.

        5 fields
        • words string[] max 10 items

          A contact who sends one of these words gets the form. Up to 10 words, 30 characters each. A word that another form of the number or an enabled Book-and-Pay word already uses is refused (word_taken).

          e.g. ["meter"]
        • header string max 60 chars

          A bold line above the body, optional.

        • body string max 1000 chars

          The text of the message that carries the form, 1 to 1,000 characters. Left out: Tap the button to open the form.

          e.g. Tap the button to send your reading.
        • button string max 20 chars

          The button's text, 1 to 20 characters. Left out: Open form.

          e.g. Open form
        • footer string max 60 chars

          A small grey line, optional.

      • after object

        What happens right after a submission.

        4 fields
        • review_step boolean default true

          A last screen that lists the answers before sending.

        • reply string max 1000 chars

          The WhatsApp message after sending, with placeholders ({reference}, {form}, {contact.name} ...). "" = no reply. Left out: a thank-you with the reference.

        • allow_additions boolean default false

          The reply gets an Add more button: text, photos and files the submitter sends in the next 10 minutes are attached to the submission.

        • status_page boolean default true

          The reply carries a button to the submitter's status page.

      • web object

        The web page of the form.

        4 fields
        • enabled boolean default true

          The form has a web page (links.web of the form).

        • verify string default optional

          Proving the WhatsApp number of a web submission with one message. optional: offered as Get updates on WhatsApp. required: the submission counts only once proven. off: never asked.

          offoptionalrequired
        • ask_email boolean default false

          Also ask for an e-mail address at the end.

        • success_text string max 500 chars

          Shown after sending. "" = the standard text.

      • notify object

        The e-mail the business gets.

        3 fields
        • email boolean default true

          E-mail the business for each submission (to the settings' notify_email).

        • to string[] max 5 items

          Up to 5 more addresses.

        • attach_files boolean default true

          Attach the submission's files.

      • calculated object[] max 20 items

        0 to 20 calculated fields: values worked out from the answers each time they change, stored in extra. Formulas (calculated fields, the calculate action, and {= ... } inside any text): numbers, 'texts' in single quotes, field keys, + - * / %, the comparisons == != > >= < <=, and / or / not, brackets, and the functions if(condition, then, else): then when the condition holds, otherwise else (null without an else). min(a, b, ...): The smallest number. max(a, b, ...): The largest number. round(x, decimals): x rounded, half away from zero; decimals 0 to 10, default 0. abs(x): x without its sign. num(x): x as a number, null when it is not one. len(x): The length of a text, or the number of items of a list. coalesce(a, b, ...): The first value that is not empty. lower(x): x in lower case. upper(x): x in upper case. concat(a, b, ...): The values joined as one text. lookup('<list>', id, '<column>'): A column of the item with that id in a list of the number, for example a price. previous('<field>'): The same contact's last value of that field in this form. count_files('<field>'): How many files a photo or document field holds. days_since(date): Whole days from a date (YYYY-MM-DD) to today; negative for a date to come. No loops and no assignment; at most 500 characters; a division by zero or a missing number gives null. Examples: reading - previous('reading'); quantity * lookup('products', product, 'price'); if(usage < 0, 'check', 'ok'); round(amount * 1.2, 2); days_since(purchase_date) > 30 and count_files('receipt') == 0.

        5 item fields
        • key string required

          Its name in extra, rules and placeholders. Same rules as a field key.

          e.g. usage
        • label string
          e.g. Usage
        • formula string required
          e.g. reading - previous('reading')
        • unit string
        • decimals integer
      • retention_days integer default 0

        0 = keep. Otherwise closed submissions and their files are erased this many days after closing (30 to 3650).

    • published object | null

      The version live on WhatsApp, or null when it was never published.

      2 fields
    • changed boolean

      true: the working copy differs from the published version: publish to make it live on WhatsApp. false also while the form was never published (published is null then).

    • flow object

      The form's state on WhatsApp.

      6 fields
      • id string

        Meta's id of the WhatsApp Flow. Empty until published.

      • status string

        Meta's status. Only PUBLISHED is sent to customers.

        DRAFTPUBLISHEDDEPRECATEDBLOCKEDTHROTTLED
      • Meta's complaints about the generated form, when there are any.

      • checked_at string

        When the status was last read from Meta. Empty: never.

      • last_error string

        Why the last publish failed. Empty when it worked.

      • can_send boolean

        true: the form can be sent inside WhatsApp now. false: its words and the send route answer with the web link.

    • counts object

      Its submissions.

      2 fields
    • fields object[]

      Every field and calculated value as a column. One form only.

      8 item fields
      • key string
      • label string
      • type string
        texttextareanumberemailphonedateselectmultiselectyesnoratingconsentphotodocumentlocationinfohidden
      • step string

        The key of its step. Empty for a calculated field.

      • internal boolean

        true: its value is in extra, not in answers.

      • unit string
      • choices object[]

        select and multiselect.

      • calculated boolean

        true: worked out by a formula.

    • created string (date-time)
    • updated string (date-time)
  • applied object any keys

    After POST /submit/forms with preset only: what the preset installed, as in the setup answer (lists, connections, forms, automations, published).

  • note string

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