Create an automation: when, if, do
https://api.app2email.com/v1/{number}/submit/automations 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
-
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
-
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 -
Its place in the list, lowest first.
-
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 -
The trigger's options (see trigger). {} when it has none.
e.g.{"to":["accepted"],"from":[]} -
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
- not_equals any
- in any[]
- not_in any[]
- contains 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.
-
1 to 20 actions, run in order.
32 item fields
-
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.
-
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 -
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.
- file string
reply. The key of a photo or document field whose files are sent along, or "".
- link boolean
reply. true: add a button that opens the submitter's status page.
- form string
send_form. The key of the form to send.
-
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.
-
http. Query parameters: {name: value}, up to 30.
-
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 -
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).
-
mcp. The tool's arguments: {name: value}, typed like a JSON body.
-
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"} -
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
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
-
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 - 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 -
The trigger's options (see trigger). {} when it has none.
e.g.{"to":["accepted"],"from":[]} -
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
- not_equals any
- in any[]
- not_in any[]
- contains 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.
-
1 to 20 actions, run in order.
32 item fields
-
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.
-
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 -
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.
- file string
reply. The key of a photo or document field whose files are sent along, or "".
- link boolean
reply. true: add a button that opens the submitter's status page.
- form string
send_form. The key of the form to send.
-
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.
-
http. Query parameters: {name: value}, up to 30.
-
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 -
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).
-
mcp. The tool's arguments: {name: value}, typed like a JSON body.
-
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"} -
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 integere.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.