Create an automation: when, if, do

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

Scope: submissions:manage. Not with a sandbox key. trigger says when it runs (submitted, a stage change, a button the customer pressed, overdue, manual ...), conditions is a rule that must hold (or null), actions run in order: reply, e-mail, move the stage, assign, calculate, call an outside system through a connection and save parts of its answer, wait, and more. The SubmitAutomationInput schema lists every trigger, action, placeholder and formula function. The document is checked as a whole: 400 invalid_automation with each problem's path and a fix. Before switching one on, try it on a real submission with POST /submit/automations/try. A number has at most 200 automations.

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

  • 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

Responses

201 Made.
Fields
  • success boolean
  • request_id string
  • automation object

    A saved automation: the document that was sent (SubmitAutomationInput explains every trigger, action, placeholder and formula function) plus its id and counters.

    16 fields
    • name string 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
    • trigger string

      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[] 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.

      • 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
    • id integer
      e.g. 31
    • sentence string

      The automation in one sentence, as the dashboard lists it.

    • runs integer

      How often it ran.

    • failures integer
    • last_run string (date-time) | null
    • last_error string
    • created string (date-time)
    • updated string (date-time)

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