The guide to Submit-Info: build a form from a list of questions, publish it to WhatsApp and a web page, work submissions through stages in a shared inbox with roles, automate replies and calls to your own systems, and set everything up through the API or an AI agent.
You write a form as a plain list of questions. app2email turns it into a form inside WhatsApp and a web page with the same steps. A customer, or a member of your own field staff, fills it in and gets a reference. The answers and files become a submission in a shared inbox, where it moves through your stages and sets off your automations.
One idea
Form, then submission, then stages, then automations, then connections. A quote request, an application, a meter reading, a problem report, a completed job, a proof of delivery and an expense receipt are all the same thing with different questions and different stage names. Each comes as a template you can install and change.
Nothing changes for a number that never opens Submit-Info. A form that is not published to WhatsApp yet still works: its word answers with the web page's link.
A form has 1 to 12 steps, and a step has a title and 1 to 12 questions. There is no canvas and nothing to draw: the same list drives the form on WhatsApp, the web page, the checks on the answers, the columns of the table view, the exports and the API. The preview beside the editor shows the form as a person sees it.
| Type | What the person gives | What you can set |
|---|---|---|
text | A short answer | shortest and longest length, a pattern |
textarea | A longer answer | shortest and longest length |
number | A number | lowest and highest value, decimals, a unit such as kWh |
email | An e-mail address | |
phone | A phone number | |
date | A date | how many days back or ahead it may be |
select | One choice | the choices (2 to 200), or a list of yours |
multiselect | Several choices | the choices (2 to 20), fewest and most to tick |
yesno | Yes or No | |
rating | A mark from 1 up to 3-10 | the highest mark |
consent | A sentence to agree to | whether it must be ticked |
photo | One or more photos | how many (1 to 10); camera, gallery or either |
document | One or more files | how many (1 to 10); any file, PDF, images or office files |
location | Where the person is | on WhatsApp the location request; on the web a button and an address line |
info | Text you show | nothing is asked or stored |
hidden | A value that comes with the link | such as a job number; nothing is shown |
{contact.name}.The web page. The same steps at /form/your-code/form-key. It asks for a name and a WhatsApp number last. After sending, the person sees the reference and can tap "Get updates on WhatsApp", which confirms their number with one message; a form can be set to require that. A personal link (sent by you) already knows who the person is. To put the form on your own site, use the snippet under Share; if the form asks for a location, add allow="geolocation" to the iframe. Photos are made smaller in the browser before they are uploaded; a file can be up to 10 MB.
Who may send. Anyone (the usual choice), or only the numbers you list or contacts with a tag of yours. That is how a form stays with your field staff. The word status answers a person with the stage of their recent submissions.
Stages belong to the form. A new form starts with New, In progress and Done; rename them, add your own (2 to 12), and choose a colour. Every stage is one of three kinds: open, done or cancelled.
A reply written outside WhatsApp's reply time is kept and delivered when the person next writes. The inbox says so on the reply.
The Inbox shows Open, Mine, Unassigned, Done and All, plus the views you save. Search and filter by form, stage, assignee, tag, channel and date. Three layouts: a list, a table (one form: every question is a column) and a board (one form: a column for each stage). Tick several rows to change the stage, assign, tag, export or delete them together.
A submission shows its answers, its files, where it was sent from, and one history of everything that happened to it: stage changes with who and why, notes, replies in both directions, files, and every automation step with its result. At the bottom you write either an internal note or a WhatsApp reply. Export any view as CSV, Excel or JSON, and one submission as a PDF.
Your team. Invite people by e-mail to just the inbox. They get a light app of their own at /desk and never see the rest of your account. A role is a starting set of abilities, and each ability can be switched on or off for one person.
| Role | Starts with |
|---|---|
| Owner, Admin | Everything, including forms, automations, connections and the team |
| Manager | Notes, replies, editing answers, changing the stage, assigning, files, export, delete, running manual actions |
| Agent | Notes, replies, editing answers, changing the stage, files, running manual actions. Can take a submission for themselves |
| Viewer | Can read, nothing else |
You can also narrow what a person sees: only some forms, only what is assigned to them (with or without unassigned ones to pick up), and contact details hidden. Every action of a team member is written to the submission's history.
The person's own page. Each submission has a private page at /s/a-long-code, with no login: the stage, the messages and stage changes so far, your open question with its buttons, and "Add information" when the form allows it. Internal notes and internal fields are never on it.
Privacy. Erasing a contact erases their submissions and files. A form can have a keep-for time, after which closed submissions are erased.
An automation reads as a sentence: when something happens, if some things are true, do these things in order. "When a Quote request is submitted, if quantity is 20 or more, assign it to Managers and e-mail the owner."
| When | It runs when |
|---|---|
submitted | a submission is complete and its files have arrived |
status_changed | the stage changed (optionally: to or from certain stages) |
assigned | the person it is assigned to changed |
updated | answers or internal fields were edited |
note_added | a team member wrote a note |
file_added | a file was added later |
customer_replied | the person who sent it added text or files |
button | the person pressed a button of one of your replies |
overdue | it is still in the same stage after a number of minutes |
due | its due time passed while it was open |
manual | a team member presses the action's button on the submission |
If: rules on answers, calculated values, the stage, the channel, tags and the assignee. A rule is a field, an operator and a value: equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Join rules with all (and) or any (or).
| Do | What it does |
|---|---|
set_status | move it to a stage, with a note |
assign | to a member, in turn over a role, to the least busy of a role, or to nobody |
set_field, calculate | write an internal field, or work one out with a formula |
tag, set_priority, set_due | tags, priority, a due time |
reply | a WhatsApp message to the person, with up to 3 buttons that each move the stage, a file, or the link to their status page |
ask_location | ask the person to share where they are |
send_form | send a follow-up form; what comes back is attached to this submission |
email | to the owner, the assignee, the person, or any address, with the files attached |
notify | an e-mail to the assignee, a role, or everyone in the team |
http, openapi, mcp | call a connection and keep parts of the answer in fields |
wait | carry on later, only if the conditions still hold |
stop | end here |
Every run is logged step by step: what was sent, what came back, how long it took. "Try with a submission" runs an automation against a real submission without changing or sending anything. A call to an outside system that fails is tried again after 1 minute, 10 minutes and 1 hour; after that the automation is marked as failed and your webhooks get submit.automation_failed. Automations that set each other off are stopped after three levels.
{
"name": "Large quotes go to a manager",
"form": "quote_request",
"enabled": true,
"trigger": "submitted",
"options": {},
"conditions": {
"all": [
{
"field": "quantity",
"gte": 20
}
]
},
"actions": [
{
"type": "assign",
"to": "role:manager"
},
{
"type": "set_priority",
"priority": "high"
},
{
"type": "email",
"to": [
"owner"
],
"subject": "Large quote {reference}",
"body": "{contact.name} asked for a quote.\n\n{answers}\n\n{desk_link}",
"attach_files": true
}
]
}quote_amount is an internal field your team fills in before moving the submission to Quoted. The reminder goes out only if the submission is still in Quoted.
{
"name": "Send the quote and ask for an answer",
"form": "quote_request",
"enabled": true,
"trigger": "status_changed",
"options": {
"to": [
"quoted"
],
"from": []
},
"conditions": {
"field": "status",
"equals": "quoted"
},
"actions": [
{
"type": "reply",
"text": "Your quote {reference}: {quote_amount}. Would you like to go ahead?",
"link": true,
"buttons": [
{
"id": "accept",
"title": "Accept",
"set_status": "accepted"
},
{
"id": "decline",
"title": "Decline",
"set_status": "declined"
}
]
},
{
"type": "wait",
"minutes": 4320
},
{
"type": "reply",
"text": "A reminder about your quote {reference}. Tap Accept or Decline, or write to us with any question."
}
]
}usage is a calculated value: reading - previous('reading').
{
"name": "Query a reading that looks wrong",
"form": "meter_reading",
"enabled": true,
"trigger": "submitted",
"options": {},
"conditions": {
"any": [
{
"field": "usage",
"lt": 0
},
{
"field": "usage",
"gt": 2000
}
]
},
"actions": [
{
"type": "set_status",
"status": "queried",
"note": "Usage {usage} kWh is outside the usual range."
},
{
"type": "notify",
"to": "role:manager",
"text": "Reading {reference} for meter {meter_no} needs a check: usage {usage} kWh."
}
]
}A connection is an outside system an automation can call. Your account's webhooks need none: they receive every submission event as it happens (see the events). For everything else there are three kinds. "Test" on a connection, and "Try with a submission" on an action, show the real request and the real answer before anything is switched on.
A base address and a way to sign in (none, a bearer token, a header, user name and password, or a key in the address). The action names the method, the path, and a JSON body. save keeps parts of the answer in fields of the submission.
{
"key": "billing",
"name": "Billing",
"kind": "http",
"base_url": "https://billing.example.com/api",
"auth": {
"type": "bearer",
"secret": "YOUR_BILLING_TOKEN"
},
"enabled": true
}{
"type": "http",
"connection": "billing",
"method": "POST",
"path": "/readings",
"body": {
"meter": "{meter_no}",
"reading": "{reading}",
"usage": "{usage}",
"reference": "{reference}",
"photo": "{files.photo}"
},
"save": {
"billing_id": "$.id"
},
"on_fail": "retry"
}Give the address of an OpenAPI 3 document in JSON, or paste it. app2email reads its operations; the action picks one by its id and fills its parameters. YAML and Swagger 2 documents are not read.
{
"key": "helpdesk",
"name": "Helpdesk",
"kind": "openapi",
"base_url": "https://helpdesk.example.com/api",
"spec_url": "https://helpdesk.example.com/openapi.json",
"auth": {
"type": "header",
"name": "X-Api-Token",
"secret": "YOUR_HELPDESK_TOKEN"
},
"enabled": true
}{
"type": "openapi",
"connection": "helpdesk",
"operation": "createTicket",
"params": {
"title": "Problem {reference}: {category}",
"description": "{description}",
"reporter": "{contact.phone}"
},
"save": {
"ticket_id": "$.id"
},
"on_fail": "retry"
}Give the address of an MCP server (streamable HTTP) and its token. app2email lists the server's tools; the action picks one and fills its arguments. $text keeps the tool's whole answer as text.
{
"key": "dispatch",
"name": "Dispatch",
"kind": "mcp",
"base_url": "https://dispatch.example.com/mcp",
"auth": {
"type": "bearer",
"secret": "YOUR_DISPATCH_TOKEN"
},
"enabled": true
}{
"type": "mcp",
"connection": "dispatch",
"tool": "close_job",
"arguments": {
"job_id": "{job}",
"summary": "{work_done}",
"minutes": "{time_spent}",
"photos": "{files.photos}"
},
"save": {
"dispatch_answer": "$text"
},
"on_fail": "continue"
}Good to know. A value that is exactly one placeholder keeps its type (a number stays a number, a list stays a list). Secrets are stored encrypted, never shown again and never returned by the API. Addresses must be https and public: private, local and internal addresses are refused, and redirects are not followed. A call may take 15 seconds and its answer may be 256 KB. In save, a path is $ (the whole answer) or a plain path such as $.data.items[0].id.
Every text and every parameter of an action can use placeholders in curly brackets. A name that is not known stays as you typed it.
| Placeholder | Becomes |
|---|---|
{<field key>} | the answer to that question (also internal fields, calculated values and values an automation saved) |
{reference} | the reference, for example MR-7Q3M2A |
{form} {form_key} | the form's name and its key |
{status} {status_name} | the stage's key and its name |
{channel} | whatsapp, web, api or staff |
{priority} {tags} | the priority and the tags |
{created} {updated} {due} | the times |
{contact.name} {contact.phone} {contact.email} | the person who sent it |
{assignee.name} {assignee.email} | the team member it is assigned to |
{link} | the person's own status page |
{desk_link} | the submission in your team's inbox |
{answers} | all answers as "Label: value" lines |
{files} {files.<field key>} | links to all files, or to the files of one question; another system can fetch them for 7 days |
{note} | the note of the stage change, or the note that set the automation off |
{button} | the button the person pressed |
{business} | your business name |
{submission} | in a JSON body: the whole submission as an object |
{= formula } | a formula worked out in place, for example {= round(qty * 1.1, 2) } |
Used by calculated values, by the calculate action, and inside {= ... } in any text. A formula works with numbers, texts in single quotes and the keys of your questions. It can be 500 characters long. Dividing by zero, or a number that is missing, gives an empty value instead of an error.
| You write | Meaning |
|---|---|
+ - * / % | arithmetic on numbers and answers |
== != > >= < <= | comparisons |
and or not ( ) | logic and brackets |
if(condition, a, b) | a when the condition holds, otherwise b |
min(a, b, ...) max(a, b, ...) | the smallest, the largest |
round(x, n) abs(x) | rounding to n decimals, the size of a number without its sign |
num(x) len(x) | a text as a number; the length of a text or a list |
coalesce(a, b) | a, or b when a is empty |
lower(x) upper(x) concat(a, b, ...) | texts |
lookup('list', id, 'column') | a column of a row of one of your lists, for example a price |
previous('field') | the same person's last answer to that question |
count_files('field') | how many files a question holds |
days_since(date) | days from a date until today |
Examples: qty * lookup('prices', product, 'price') for an instant estimate; reading - previous('reading') for usage; if(amount > 500, 'manager', 'agent') to decide who approves.
Everything above is in the REST API under /v1/{number}/submit, where {number} is your WhatsApp number with the country code, digits only. Send your API key as Authorization: Bearer YOUR_API_KEY (the X-API-KEY header is accepted too). The key needs the scope submissions:manage; keys with full access have it, the Default key does not. Sandbox keys cannot write.
GET /submit/guide: one JSON document with the whole vocabulary: question types with their options and limits, stage rules, triggers, operators, actions with their parameters, placeholders, formula functions, the templates, and worked examples.POST /submit/setup with "dry_run": true: nothing is written; every problem comes back with its path and a sentence saying how to fix it.POST /submit/setup without dry_run: lists, connections, forms and automations are applied together. With any problem nothing is written.POST /submit/forms/{key}/publish, or name the forms in "publish" of the setup document.GET /submit/forms/{key} returns them), then read GET /submit/submissions or listen to the webhook events.Save the document below as setup.json and post it. Replace 61400000000 with your number. It checks a meter reading solution: a list of sites, a connection to a billing system, one form with three stages and a calculated usage, and two automations. Remove "dry_run": true to apply it. Existing forms, lists and connections with the same key are replaced; automations are matched by name within the form. "preset": "..." in place of the parts installs one of the templates (GET /submit/presets lists them).
curl -X POST "https://api.app2email.com/v1/61400000000/submit/setup" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d @setup.json{
"dry_run": true,
"settings": {
"enabled": true,
"config": {
"business_name": "Northside Energy",
"default_prefix": "NE"
}
},
"lists": [
{
"key": "sites",
"name": "Sites",
"items": [
{
"id": "north",
"title": "North depot"
},
{
"id": "south",
"title": "South depot"
}
]
}
],
"connections": [
{
"key": "billing",
"name": "Billing",
"kind": "http",
"base_url": "https://billing.example.com/api",
"auth": {
"type": "bearer",
"secret": "YOUR_BILLING_TOKEN"
},
"enabled": true
}
],
"forms": [
{
"key": "meter_reading",
"name": "Meter reading",
"definition": {
"title": "Meter reading",
"description": "Send us your reading. It takes about a minute.",
"prefix": "MR",
"steps": [
{
"key": "reading",
"title": "Your reading",
"text": "",
"show_if": null,
"fields": [
{
"key": "site",
"type": "select",
"label": "Site",
"required": true,
"list": "sites"
},
{
"key": "meter_no",
"type": "text",
"label": "Meter number",
"help": "Printed on the front of the meter",
"required": true,
"max_length": 30
},
{
"key": "reading",
"type": "number",
"label": "Reading",
"required": true,
"min": 0,
"decimals": 0,
"unit": "kWh"
},
{
"key": "photo",
"type": "photo",
"label": "Photo of the meter",
"required": false,
"max_files": 1,
"source": "any"
},
{
"key": "billing_id",
"type": "text",
"label": "Billing record",
"internal": true
}
]
}
],
"stages": [
{
"key": "received",
"name": "Received",
"kind": "open",
"color": "blue",
"set_by": [],
"require_note": false,
"message": ""
},
{
"key": "queried",
"name": "Queried",
"kind": "open",
"color": "amber",
"set_by": [],
"require_note": true,
"message": "We have a question about your reading {reference}. We will be in touch."
},
{
"key": "checked",
"name": "Checked",
"kind": "done",
"color": "green",
"set_by": [],
"require_note": false,
"message": ""
}
],
"who": {
"mode": "anyone",
"numbers": [],
"tag": ""
},
"trigger": {
"words": [
"meter",
"reading"
],
"header": "",
"body": "Tap the button to send your reading.",
"button": "Open form",
"footer": ""
},
"after": {
"review_step": true,
"reply": "Thanks {contact.name}. We have your reading - reference {reference}.",
"allow_additions": false,
"status_page": true
},
"web": {
"enabled": true,
"verify": "optional",
"ask_email": false,
"success_text": "Thank you. We have your reading."
},
"notify": {
"email": true,
"to": [],
"attach_files": true
},
"calculated": [
{
"key": "usage",
"label": "Usage",
"formula": "reading - previous('reading')",
"unit": "kWh",
"decimals": 0
}
],
"retention_days": 0
}
}
],
"automations": [
{
"name": "Query a reading that looks wrong",
"form": "meter_reading",
"enabled": true,
"trigger": "submitted",
"options": {},
"conditions": {
"any": [
{
"field": "usage",
"lt": 0
},
{
"field": "usage",
"gt": 2000
}
]
},
"actions": [
{
"type": "set_status",
"status": "queried",
"note": "Usage {usage} kWh is outside the usual range."
},
{
"type": "notify",
"to": "role:manager",
"text": "Reading {reference} for meter {meter_no} needs a check: usage {usage} kWh."
}
]
},
{
"name": "Send good readings to billing",
"form": "meter_reading",
"enabled": true,
"trigger": "submitted",
"options": {},
"conditions": {
"all": [
{
"field": "usage",
"gte": 0
},
{
"field": "usage",
"lte": 2000
}
]
},
"actions": [
{
"type": "http",
"connection": "billing",
"method": "POST",
"path": "/readings",
"body": {
"meter": "{meter_no}",
"reading": "{reading}",
"usage": "{usage}",
"reference": "{reference}",
"photo": "{files.photo}"
},
"save": {
"billing_id": "$.id"
},
"on_fail": "retry"
},
{
"type": "set_status",
"status": "checked",
"note": "Sent to billing as {billing_id}."
}
]
}
],
"publish": [
"meter_reading"
]
}The answer of the real call (without dry_run):
{
"success": true,
"request_id": "req_...",
"applied": {
"lists": [
"sites"
],
"connections": [
"billing"
],
"forms": [
"meter_reading"
],
"automations": [
"Query a reading that looks wrong",
"Send good readings to billing"
],
"published": [
"meter_reading"
]
},
"problems": []
}GET / PUT /submit/settings.POST /submit/forms/{key}/send to send a form to a number with values filled in.PUT /submit/lists/{key} replaces the rows of a list.updated_after for syncing; CSV with ?format=csv), create, read by id or reference, update (stage, note, priority, assignee, due time, tags, answers, internal fields), add a note, reply with buttons, add a file, delete.POST /submit/automations/try, and the run log.Every webhook of your account gets every event. Each carries the submission as it is at that moment; file links in it work for 7 days.
| Event | When |
|---|---|
submission.created | a submission exists (its files may still be arriving) |
submission.files_ready | its files are stored |
submission.updated | answers, internal values, priority, tags or the due time changed |
submission.status_changed | the stage changed |
submission.assigned | the assignee changed |
submission.note_added | a note was written |
submission.customer_replied | the person added text, files or a follow-up, or pressed a button |
submission.deleted | deleted or erased |
submit.automation_failed | an automation gave up after its retries |
Each route is also a tool on app2email's hosted MCP server, so an assistant can do the whole setup in a conversation: get_submit_guide, apply_submit_setup, list_submit_presets, create_form, publish_form, send_form, list_submissions, get_submission, update_submission, reply_to_submission, create_automation, try_automation, set_connection, test_connection and more. A good first message to the assistant: "Read the Submit-Info guide, then set up a problem report form with photos and a location, and tell my managers about urgent ones."
claude mcp add --transport http app2email https://api.app2email.com/mcp --header "Authorization: Bearer YOUR_API_KEY"More on connecting assistants and automation tools: Automation tools and agents.
| Limit | Value |
|---|---|
| Forms per number | 100 |
| Steps in a form, questions in a step | 12 and 12 (60 questions in a form, one location question) |
| Lists | 50, each up to 1,000 rows |
| Automations, connections, team members | 200, 30, 200 |
| Files in one submission | 60 |
| File size | 25 MB from WhatsApp, 10 MB from the web page or the API |
| A note or a reply | 4,000 characters |
| Tags on a submission | 20 |
| Calls to outside systems | 60 a minute and 2,000 a day per number; 15 seconds and 256 KB per call |
| Run log | kept 30 days |
Everything above is set on the dashboard under Integrations, Submit-Info. Questions: support@app2email.com.