Apply or dry-run a whole setup: forms, lists, automations

POST https://api.app2email.com/v1/{number}/submit/setup
scope: submissions:manage sandbox: refused MCP: apply_submit_setup

Scope: submissions:manage. A sandbox key may only make a dry run. The one call that builds a solution: settings, lists, connections, forms and automations in one document (the SubmitSetup schema; GET /submit/guide has complete examples). Always send it with dry_run true first: the answer lists every problem with its path and a fix, and writes nothing. When problems is empty, send it again without dry_run. What exists under the same key is replaced (lists, connections, forms by key; automations by name within a form); everything else is left alone. With any problem nothing is written at all: 400 invalid_setup with the problems in error.details. publish names the forms to publish to WhatsApp after a clean apply; otherwise call POST /submit/forms/{key}/publish. A form that cannot be published does not undo the rest: the answer is still 200, applied.published names the forms that went live and problems says why another did not. preset in place of the parts installs a ready-made solution. If a save fails half-way (rare) the answer is 500 with error.details.applied: send the same document again, every part replaces what is there.

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

Body application/json required

  • dry_run boolean default false

    true: check only. The answer lists every problem and what would be written; nothing is changed.

  • replace boolean default true

    Left out or true: a form whose key already exists is replaced by the one in the document. false: such a form is not overwritten - the answer is 409 form_exists and nothing is written. Lists, connections and automations of the same key / name are always replaced.

  • preset string

    A preset's key, instead of lists, connections, forms and automations.

    e.g. quote
  • settings object

    As PUT /submit/settings.

    2 fields
    • enabled boolean

      true switches Submit-Info on for the number.

    • config object more keys allowed

      The number's Submit-Info settings.

      11 fields
      • The {business} placeholder and the name on the web pages. "" = the number's verified name.

      • 2 to 4 letters A-Z: the reference prefix of forms that have none.

        e.g. SI
      • menu_words string[] max 10 items

        A contact who sends one of these gets the form (one form) or a menu of the forms (several). [] = no menu.

      • menu_text string

        The text above the menu.

      • status_words string[] max 5 items

        A contact with a submission of the last 90 days who sends one of these gets its stage.

      • other_words_limit integer 0–100 default 10

        A form's word starts the form only when the message has fewer than this many other words, so a long message never starts a form. 0 = a message of any length. Menu and status words also need a message of at most 5 words.

      • notify_email string

        Where the business's e-mails go. "" = the number's Default To address. "off" = none.

      • timezone string

        "" = the number's time zone.

        e.g. Australia/Sydney
      • brand object

        The look of the web form and the status page.

        3 fields
      • views object[] max 20 items

        Saved inbox views the whole team shares.

        3 item fields
      • retention_days integer default 0

        For forms that set none: 0 = keep, else closed submissions are erased after this many days (30 to 3650).

  • lists object[]

    As PUT /submit/lists/{key}, with the key inside.

    3 item fields
    • key string required
      e.g. products
    • name string required
    • items object[] required
      3 item fields
      • id string required

        What is stored as the answer. Unique in the list.

        e.g. pump-s
      • title string required
        e.g. Pump, small
      • description string
  • connections object[]

    As PUT /submit/connections/{key}, with key inside each one.

    8 item 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.

    • auth object
      4 fields
      • type string required

        none: No sign-in. bearer: Authorization: Bearer <secret>. header: The header called name carries the secret. basic: Basic sign-in with username and the secret as the password. query: The query parameter called name carries the secret.

        nonebearerheaderbasicquery
      • name string

        header: the header's name. query: the parameter's name.

      • username string

        basic only.

      • secret string

        The token, key or password. Write-only: never shown again. Left out: the stored one is kept.

    • spec object any keys

      openapi only: the OpenAPI document itself, posted once instead of spec_url.

  • forms object[]

    As POST /submit/forms.

    3 item fields
    • key string required
      e.g. quote
    • name string required
      e.g. Quote request
    • definition object required

      A form as one document. The same JSON drives the WhatsApp form (app2email generates it: there is nothing to draw), the web page, the checks on every answer, the inbox columns and the exports. steps hold the fields; stages are the states a submission moves through; who, trigger, after, web, notify, calculated and retention_days are optional and take their defaults when left out. Limits: 12 steps, 12 fields in a step, 60 fields in a form, one location field, 64 KB of JSON. A save is checked as a whole: with any problem nothing is saved and the 400 answer lists each one with its path and a fix. The saved form comes back normalized, with every default filled in. Saving changes the working copy; WhatsApp keeps showing the published version until POST /submit/forms/{key}/publish is called again. Conditions: a step or a field with show_if appears only when its rule holds, and the rule may only look at fields of earlier steps. A rule is {"field": "<key>", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {"all": [rule, ...]} (every one) or {"any": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {"field": "deliver", "equals": true}; {"all": [{"field": "amount", "gt": 5000}, {"field": "category", "in": ["plant", "vehicle"]}]}.

      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 pattern ^[a-z][a-z0-9_]{0,39}$

          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 1–60 chars

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

          e.g. Your reading
        • text string max 500 chars

          Shown above the fields, up to 500 characters.

        • show_if object more keys allowed

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

          14 fields
          • field string

            A field key (or an extra key). Automations may also name status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone.

            e.g. amount
          • equals any
          • in any[]
          • not_in any[]
          • empty boolean
          • not_empty boolean
          • gt any
          • gte any
          • lt any
          • lte any
          • all object[]

            A group: every rule in it must hold.

          • any object[]

            A group: at least one rule in it must hold.

        • fields object[] required 1–12 items

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

          26 item fields
          • key string required pattern ^[a-z][a-z0-9_]{0,39}$

            The field's name in answers, rules, placeholders, formulas and exports: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique in the form, not a reserved word, not starting with _. Reserved: reference, status, status_name, form, form_key, channel, contact, link, id, created, updated, assignee, priority, tags, due, files, flow_token, screen, error_message, error, answers, extra, submission, note, button, business, desk_link, status_kind, verified, files_count, prefill, confirm, true, false, null, and, or, not.

            e.g. reading
          • type string required

            The field type decides the answer's JSON type, the keys that apply and how WhatsApp shows it. text (value: string; on WhatsApp: text input): min_length, max_length, pattern. textarea (value: string; on WhatsApp: text area): min_length, max_length, pattern. number (value: number; on WhatsApp: number input): min, max, decimals, unit. email (value: string; on WhatsApp: e-mail input). phone (value: string; on WhatsApp: phone input). 6 to 20 digits. date (value: string, YYYY-MM-DD; on WhatsApp: date picker): min_days, max_days. select (value: string: the id of the choice; on WhatsApp: radio buttons up to 8 choices, a dropdown above that): choices, list. While its list is empty a select is not required and not checked. multiselect (value: array of strings: the ids of the choices; on WhatsApp: checkboxes): choices, min_choices, max_choices. yesno (value: boolean; on WhatsApp: Yes / No radio buttons). rating (value: number, 1 to max; on WhatsApp: radio buttons 1 to max): max. consent (value: boolean; on WhatsApp: a tick box). The label is the sentence to agree to (at most 120 characters). required true = it must be ticked. photo (value: array of file ids; on WhatsApp: photo picker): max_files, source. WhatsApp allows one photo or document picker on a screen: a step with several is split into several screens by itself. document (value: array of file ids; on WhatsApp: document picker): max_files, kinds. One picker on a screen, as for photo. location (value: string: the address text; the pin is the submission's location {lat, lng, name, address}; on WhatsApp: asked after the form with WhatsApp's own Send location request). On the web page: a Use my location button and an address line. One location field in a form; required is not enforced for it. info (value: nothing is stored; on WhatsApp: a heading (the label) and text): text. hidden (value: string; on WhatsApp: nothing is shown). The value is the field's default (usually {prefill.<key>}), or the prefill value given under the field's own key: a job number or an account that arrives with the link or the send call.

            texttextareanumberemailphonedateselectmultiselectyesnoratingconsentphotodocumentlocationinfohidden
          • label string required 1–200 chars

            The question, 1 to 200 characters. A label longer than WhatsApp allows on the input is moved into text above it by itself.

            e.g. Meter reading
          • help string max 80 chars

            A hint with the input, up to 80 characters.

          • required boolean

            true: must be answered (consent: must be ticked). Default false. Not enforced for a location field: the pin arrives after the form.

          • internal boolean default false

            true: never asked. Staff, the API or an automation fill it (a quote amount, a decision reason, an id another system returned). Its value is stored in the submission's extra and shows in the inbox and in exports. Only for the types text, textarea, number, email, phone, date, select, multiselect, yesno and rating; an internal field is never required and has no show_if. Default false.

          • show_if object more keys allowed

            A rule on fields of EARLIER steps: the field is asked only when the rule holds. The rule may look at fields that are asked or hidden, not at internal or info fields. A field that is not shown counts as empty for the rules after it. null = always.

            14 fields
            • field string

              A field key (or an extra key). Automations may also name status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone.

              e.g. amount
            • equals object
            • not_equals object
            • in array
            • not_in array
            • contains object
            • empty boolean
            • not_empty boolean
            • gt object
            • gte object
            • lt object
            • lte object
            • all array

              A group: every rule in it must hold.

            • any array

              A group: at least one rule in it must hold.

          • default string

            The starting value, up to 500 characters: a literal, or the placeholders {contact.name}, {contact.phone}, {contact.<custom field>}, {prefill.<key>} (prefill = the values given when the form is sent). Not for photo, document, location and info.

          • sensitive boolean default false

            true: the value is masked in WhatsApp's own summary of the form. Only for the types text, textarea, number, email, phone, date, select, multiselect, yesno and rating. Default false.

          • min_length integer min 0

            text, textarea. Fewest characters. 0 = none.

          • max_length integer min 0

            text, textarea. Most characters. 0 = the type's limit (text 200, textarea 2,000).

          • pattern string max 200 chars

            text, textarea. A regular expression the whole answer must match, up to 200 characters.

          • min number | null

            number. Smallest value. null = none.

          • max number | null

            number: the largest value, null = none. rating: the highest rating, 3 to 10, default 5.

          • decimals integer 0–6 default 0

            number. Decimal places allowed, 0 to 6. Default 0.

          • unit string

            number. Shown after the value, for example kWh. Up to 20 characters.

            e.g. kWh
          • min_days integer | null

            date. Earliest day, counted from today (negative = in the past). null = none.

          • max_days integer | null

            date. Latest day, counted from today. null = none.

          • choices object[]

            select: 2 to 200 choices (or use list). multiselect: 2 to 20 choices.

          • list string

            select. Instead of choices: the key of a list of the number (GET /submit/lists). The list is read each time the form opens, so changing it needs no publish. At most 200 items are shown.

            e.g. products
          • min_choices integer min 0 default 0

            multiselect. Fewest ticks. 0 = none.

          • max_choices integer min 0 default 0

            multiselect. Most ticks. 0 = no limit.

          • max_files integer 1–10 default 1

            photo, document. How many files, 1 to 10.

          • source string default any

            photo. Where the photo may come from.

            anycameragallery
          • kinds string[]

            document. What may be sent: ["any"] (default), or some of pdf, image, office.

          • text string max 1000 chars

            info. The text shown, up to 1,000 characters.

      • 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 pattern ^[a-z][a-z0-9_]{0,39}$

          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.

          opendonecancelled
        • color string

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

          greybluegreenamberredpurple
        • set_by string[]

          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.

          owneradminmanageragentviewer
        • require_note boolean

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

        • message string max 1000 chars

          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 max 60 chars
          e.g. Usage
        • formula string required max 500 chars
          e.g. reading - previous('reading')
        • unit string
        • decimals integer 0–6
      • retention_days integer default 0

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

  • automations object[]

    As POST /submit/automations.

    8 item fields
    • name string required max 80 chars

      What it is called in the list, up to 80 characters. POST /submit/setup replaces an automation with the same name on the same form.

      e.g. Large quotes go to a manager
    • form string

      The key of the form it belongs to, or "" for every form.

      e.g. quote
    • enabled boolean default true
    • position integer min 0

      Its place in the list, lowest first.

    • trigger string required

      When it runs. submitted: A submission is complete: its files are stored (or 3 minutes passed without them, which is noted on the submission). status_changed: The stage changed. Options - to: Stage keys it moved to. [] = any. from: Stage keys it moved from. [] = any. assigned: The assignee changed. updated: Answers or internal fields were edited. Options - fields: Only when one of these field keys changed. [] = any. note_added: A member or the API wrote a note. file_added: A file was added after the submission was made. customer_replied: The submitter added text or files: after tapping Add more, with a follow-up form, or on their status page. button: The submitter pressed a button of a reply. Options - button: The button's id (a-z, 0-9 and _, up to 20 characters). "" = any button. overdue: The submission is still in the same stage after this long. Fires once per stay in a stage. Options - minutes: Needed: 5 to 43200 (30 days). stages: Only in these stage keys. [] = every open stage. due: The due time passed while the submission is open. Fires once per due time. manual: A member presses its button on the submission, or POST /submit/submissions/{id}/run names it. Options - label: The button's text, up to 30 characters. Left out: the automation's name.

      submittedstatus_changedassignedupdatednote_addedfile_addedcustomer_repliedbuttonoverdueduemanual
    • options object any keys

      The trigger's options (see trigger). {} when it has none.

      e.g. {"to":["accepted"],"from":[]}
    • conditions object more keys allowed

      Must hold for the actions to run. In an automation a rule's field may also be status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone. null = always.

      14 fields
      • field string

        A field key (or an extra key). Automations may also name status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone.

        e.g. amount
      • equals any
      • in any[]
      • not_in any[]
      • empty boolean
      • not_empty boolean
      • gt any
      • gte any
      • lt any
      • lte any
      • all object[]

        A group: every rule in it must hold.

      • any object[]

        A group: at least one rule in it must hold.

    • actions object[] required 1–20 items

      1 to 20 actions, run in order.

      32 item fields
      • type string required

        What the action does. set_status: Move the submission to a stage. Keys: status, note. assign: Set the assignee. Keys: to. set_field: Store a value on the submission. Keys: key, value. calculate: Store the result of a formula. Keys: key, formula. tag: Add or remove tags. Keys: add, remove. set_priority: Set the priority. Keys: priority. set_due: Set the due time. Keys: minutes. reply: Message the submitter on WhatsApp (by e-mail when they gave only an e-mail address). Outside WhatsApp's reply window the message is held and announced like any reply from the Inbox. Keys: text, buttons, file, link. ask_location: Ask the submitter for their location with WhatsApp's Send location request. The pin is stored on the submission. Keys: text. send_form: Send another form as a follow-up. Its submission gets parent = this one, and customer_replied fires here when it arrives. Keys: form, text, prefill. email: Send an e-mail. Keys: to, subject, body, attach_files. notify: E-mail team members. Keys: to, text. http: Call an outside system with a plain HTTP request. Keys: connection, method, path, url, query, headers, body, save, on_fail. openapi: Call an operation of an imported OpenAPI document. Keys: connection, operation, params, body, save, on_fail. mcp: Call a tool of an MCP server. Keys: connection, tool, arguments, save, on_fail. wait: Pause. The rest runs later, and only if the conditions still hold then. Keys: minutes. stop: End the run here.

        set_statusassignset_fieldcalculatetagset_priorityset_duereplyask_locationsend_formemailnotifyhttpopenapimcpwaitstop
      • status string

        set_status. The stage key.

      • note string

        set_status. The note of the change (needed when the stage has require_note).

      • to any

        assign: member:<id> = that member. role:<role> = the members with that role in turn (round robin). least_busy:<role> = the member with that role who has the fewest open submissions. none = nobody. email: A list of up to 10: owner, assignee, submitter, an address, or a placeholder that holds an address. notify: assignee, role:<role> or all.

      • key string

        set_field, calculate. An internal field of the form, or any other name that is not one of the form's questions and not a reserved word: it is stored in extra.

      • value any

        set_field. The value, with placeholders.

      • formula string max 500 chars

        calculate. The formula (see the automation's description for the language).

      • add string[]

        tag. Tags to add.

      • remove string[]

        tag. Tags to remove.

      • priority string

        set_priority.

        lownormalhighurgent
      • minutes integer 0–525600

        set_due: minutes from now, 0 to 525600 (0 takes the due time off). wait: how long to pause, 1 to 43200.

      • text string

        reply, ask_location, send_form, notify: the message, with placeholders.

      • buttons object[] max 3 items

        reply. 0 to 3 buttons: [{id (a-z, 0-9 and _, up to 20 characters, unique in the reply), title (up to 20 characters), set_status}]. Pressing one moves the submission to set_status (when given) and fires the button trigger.

        3 item fields
        • id string required
          e.g. accept
        • title string required max 20 chars
          e.g. Accept
        • set_status string

          The stage the submission moves to when it is pressed. Left out: only the button trigger fires.

          e.g. accepted
      • file string

        reply. The key of a photo or document field whose files are sent along, or "".

      • form string

        send_form. The key of the form to send.

      • prefill object any keys

        send_form. Values for the new form: {"<field key>": value}, with placeholders. Up to 30 values.

      • subject string

        email.

      • body any

        email: the text. http, openapi: Any JSON; sent as application/json. A string that is exactly one placeholder keeps the value's type: "{quantity}" sends a number, "{submission}" the whole submission object.

      • attach_files boolean

        email. true: attach the submission's files (up to 15 MB in all; above that their links are listed). Default false.

      • connection string

        http, openapi, mcp. The connection's key (GET /submit/connections). http only: "" with a full url.

      • method string

        http.

        GETPOSTPUTPATCHDELETE
      • path string

        http. With a connection: added to its base address, for example /orders/{reference}. Each value a placeholder inserts is percent-encoded.

        e.g. /quotes
      • url string

        http. Without a connection: the full https address. Placeholders may stand in the path and the query, not in the host name.

      • query object any keys

        http. Query parameters: {name: value}, up to 30.

      • headers object any keys

        http. Extra headers: {name: value}, up to 10, each value up to 1,000 characters. Sign-in headers come from the connection only. Not allowed: Host, Content-Length, Transfer-Encoding, Connection, Cookie, Authorization, and names starting X-App2email-, Proxy-, X-Forwarded- or Content-.

      • operation string

        openapi. A function id of the connection (GET /submit/connections/{key}/functions).

        e.g. createTicket
      • params object any keys

        openapi. The operation's parameters by name: {name: value}. Path, query and header parameters go where the document says; body parameters build the JSON body.

      • tool string

        mcp. The tool's name (GET /submit/connections/{key}/functions).

      • arguments object any keys

        mcp. The tool's arguments: {name: value}, typed like a JSON body.

      • save object any keys

        http, openapi, mcp. Up to 20 values taken from the answer and stored in the submission's extra: {"<extra key or internal field>": "<JSON path>"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content).

        e.g. {"erp_id":"$.id","quote_amount":"$.total"}
      • on_fail string default retry

        http, openapi, mcp. retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent).

        retrycontinuestop
  • publish string[]

    Form keys to publish to WhatsApp after everything was written without a problem. Ignored by a dry run.

    e.g. ["quote"]

Responses

200 Checked (dry run) or applied.
Fields
  • success boolean
  • request_id string
  • dry_run boolean
  • applied object

    What was written (a dry run: what would be), by key; automations by name; published: the forms now live on WhatsApp.

    5 fields
  • note string
  • problems object[]

    Empty when the document is fine.

    4 item fields
    • path string

      Where in the body that was sent.

      e.g. definition.steps[1].fields[2].pattern
    • code string

      A short word for the kind of problem (required, too_long, duplicate_key, reserved_key, unknown_type, unknown_field, rule_later_field, unknown_list, word_taken, too_many, bad_pattern, bad_formula, bad_stage, needs_open_and_done ...).

      e.g. bad_pattern
    • message string

      What is wrong.

    • fix string

      What to change.

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