build.allanninal.dev

Part 2 of 7 · Form intake router series ~4 min read

How a form submission gets captured

The router can only route what it actually receives. So the first job is making sure a submission never gets lost between the customer clicking “Send” and the router writing it down. There are three ways a submission reaches the door: the normal way (a tiny snippet posts the form), a fallback (an email lane for forms you can’t add a snippet to), and a re-post lane (the same submission arriving twice because the customer’s connection hiccuped). All three end the same way — saved, recorded, and acknowledged — before anything slow happens.

Key takeaways

  • Three capture lanes feed one saved record: the form snippet, an email fallback, and a safe re-post.
  • The door saves the raw payload to S3 and writes a record before checking or sending anything.
  • The customer gets a “we got it” reply in well under a second, before any downstream work.
  • A submission key from the form means a double-click never creates two leads.
  • The saved record is the one source of truth; everything later reads from it.

Three lanes into one saved record

Three capture lanes reach one saved record A diagram with three vertical lane columns at the top and a single saved record at the bottom. Lane one, Form snippet: a tiny script on each website form posts the submission to the intake Function URL with a form_id and a one-time submission key; this is the normal path nearly every submission takes. Lane two, Email fallback: for a form you can't add a snippet to, the form emails a dedicated address; SES inbound writes the raw MIME to S3 and a small adapter Lambda turns it into the same submission shape so it joins the same path. Lane three, Safe re-post: if the customer's connection hiccups and the browser sends the same submission again, the one-time submission key lets the door recognize the duplicate and return the same acknowledgment instead of creating a second lead. All three lanes converge on the intake door, which saves the raw payload to s3://fir-raw/ and writes a record to the DynamoDB submissions table, then replies to the customer right away. A note at the bottom: the door saves and acknowledges before any checking or sending — capture can't fail quietly because it happens first. Lane 1 · normal Form snippet • Tiny script posts the form • Sends form_id + submission key • Hits the intake Function URL • The path nearly every form takes Lane 2 · SES inbound Email fallback • Form emails a dedicated address • SES writes MIME to S3 • Adapter reshapes into one submission • Joins the same door as Lane 1 Lane 3 · duplicate Safe re-post • Connection hiccups, browser re-sends • Same submission key arrives twice • Door recognizes the duplicate • Returns the same reply, one lead Intake door — save first, then acknowledge raw payload → s3://fir-raw/ · record → DynamoDB submissions · status: received reply to the customer in well under a second — before any checking or sending to checker, next step The door saves and acknowledges first — capture can’t fail quietly because it happens before anything slow.
Fig 2. Three capture lanes converge on one intake door. The door saves the raw payload and writes a record before it acknowledges, and acknowledges before it checks or sends. The submission key keeps a double-click from becoming two leads.

Lane 1: the form snippet (how nearly everything arrives)

Each form on your site gets a tiny snippet — a few lines of JavaScript — that sends the form’s fields to one address when the customer clicks Send. That address is a Lambda Function URL: a plain web address AWS gives a small function, with no API Gateway in front of it. The snippet adds two things to the submission: a short form_id so the router knows which form it is (contact, quote, booking), and a one-time submission_key it generates fresh each time the form is opened. You keep your existing form builder, your existing fields, your existing design; you only change where Send points.

When the post lands, the door does the smallest possible amount of work: it writes the raw body to s3://fir-raw/, writes a record to the DynamoDB submissions table with status received, and returns a small “thanks, we got it” response to the browser. That’s it. No spam check, no routing, no email yet — those all happen after the customer has already been told their message is safe. The whole round trip is well under a second because it touches only two fast services.

Lane 2: email fallback (for forms you can’t touch)

Sometimes you can’t add a snippet — a locked-down site builder, a third-party landing page, an old form you don’t want to risk editing. For those, the form is pointed at a dedicated email address instead (most form builders can email a submission). Amazon SES receives that email, writes the raw message to S3, and a small adapter Lambda turns the email’s fields into exactly the same submission shape Lane 1 produces — same form_id, a submission_key derived from the message id. From the door’s point of view there’s no difference; an email-lane submission is saved, recorded, and (where an address is present) acknowledged just like a posted one.

This lane is the safety net that means “every form on your site” is actually true, not just “every form we could rewire.”

Lane 3: safe re-post (the double-click problem)

Real browsers on real connections re-send. The customer taps Send, the spinner stalls on flaky hotel wifi, they tap again. Without care, that’s two leads, two team emails, and a prospect who looks like they asked twice. The submission_key generated when the form opened fixes this: the door writes the record using that key as the identifier, with a conditional write that only succeeds the first time. A second arrival with the same key finds the record already there, skips creating anything new, and returns the same “we got it” the first one did. One submission, one lead, one reply — no matter how many times the button is pressed.

This is the plumbing word idempotency: doing the same thing twice has the same effect as doing it once. It’s a small detail that quietly removes a whole class of “why did this customer come through three times?” confusion.

Why the door saves before it does anything else

The order is the whole point. If the door checked spam first, or tried to email the team first, then a crash or a slow tool during that work would happen before the submission was written down — and the lead would be gone with no trace. By saving the raw payload and the record first, the worst case becomes “we have the submission but haven’t delivered it yet,” which is fully recoverable: a later step (or a human) can replay it from the saved record. The customer is acknowledged off that same saved record, so even a total failure of everything downstream still leaves the prospect feeling heard and the lead sitting safely in storage.

Next post: how the checker reads that saved submission, confirms the fields, filters spam without throwing away real leads, and decides which routing rule applies.

All posts