Blog

/

How an agent signs up for things

Seventeen directory submissions, one catchall address, no one at the keyboard. The browser automation is the easy half. The part that decides whether it works is four seconds long: the site sends a mail, and the agent has to prove it can read it — once to register, and again every time the platform asks a code to let it back in.

The whole loop in 68 seconds: the agent provisions an address, registers, waits for the verification mail, clicks the link, signs in with the code that lands in the same mailbox, and submits the project. The third-party host is redacted — the interesting half of that picture is the mailbox, not the form.

The task nobody writes about

Distribution is the unglamorous half of shipping. Directory sites, launch lists, aggregators — each one wants an account, a URL, a tagline, and a click inside a verification mail. The default answer is a shared inbox and a person with a browser, which is two credentials and a queue: every submission file now contains a password, and every verification mail is a context switch.

The whole experiment was whether that queue can be deleted. Not the human, not the review — the queue. Seventeen targets, one run, one agent driving a real browser over CDP, and one mailbox on our own domain receiving everything: eight submitted, three that still need a human, four blocked, two skipped. The numbers are the honest part, and they are the reason this post exists rather than a changelog entry.

The loop is four moves

Navigation, filling and clicking are the moves everyone expects. The move that makes the loop autonomous is the fourth one — reading the mail — and it is the only one the agent cannot fake. A CDP session can click anything; it cannot receive a letter.

signup-loop.mjsjavascript
import { chromium } from "playwright";
import { Flowmails } from "@flowmails/flowmails-sdk";

const fm = new Flowmails({ apiKey: process.env.FLOWMAILS_API_KEY! });
const SITE = "twelve.tools";
const MAILBOX = "submit@flowmails.net";

// 1 · drive the page. A CDP session is the only thing that can fill a
//     form whose fields do not exist until the page's own JS runs.
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`https://${SITE}/submit`);
await page.fill('[data-field="email"]', MAILBOX);
await page.getByRole("button", { name: /^submit/i }).click();

// 2 · ask the log what arrived, not what *should* have arrived.
const { events } = await fm.events.list({ recipient: MAILBOX, limit: 20 });

// 3 · the event carries routing facts and a subject — never a body.
const mail = await fm.messages.get(events[0].messageId);
const [link] = mail.text.match(/https:\/\/[^\s"]+\/auth\/[^\s"]+/g) ?? [];

// 4 · finish the job in the same session; the cookie is the proof.
await page.goto(link);
if (await page.getByText("Your website is live").count()) {
  console.log("listed:", `https://${SITE}/flowmails-net`);
}
await browser.close();

Everything about that snippet is deliberately boring except one line: fm.events.list. The agent does not wait for an email to be pushed to it. It asks the log what has landed since it clicked, and the answer is state it can survive a restart with.

What actually breaks

Not the model, and not the protocol. The failures were all small, specific and repeatable — which is why they are worth writing down instead of remembering.

  • The submit button that is not a submit button. One form rendered a visible <button type="button"> and a hidden real submit input. Clicking the visible one does nothing; the form only moves when the page calls form.requestSubmit(). A screenshot proves nothing here — the check is whether the network saw the POST.
  • The textarea that is a code editor. A description box backed by CodeMirror ignores fill(): the value lives in the editor’s model, not the DOM node. Setting it means reaching through, editor.CodeMirror.setValue(text), after which the form’s own state agrees.
  • The wizard that lies about its step. Before you can fill anything you need to know whether you are on step 2 or step 5. The step labels are always in the DOM, so matching on text repeats the step you already finished. Match on the visible button instead.
  • The file that is validated at the end. One site accepted every field and then returned 400 {"code":"MISSING_LOGO"} — a required logo that no label marked as required. Media has to be uploaded and its URL confirmed before submit, not after.
  • The token you read too late. Magic links expire. Opening the newest mail fails with Token does not exist! if the newest is a second site’s mail to the same catchall address. The match has to include the sender and the token shape, not just the subject.
  • The captcha that is the honest end of the line. A Turnstile iframe that never loads headless is not a bug to work around; it is the site saying a human has to be present. Hand it over. Everything this post claims was done on the other side of that line.

The mailbox end of the loop

A catchall domain means one address can be everything. submit@flowmails.net receives any local part, so there is no per-site inbox to provision, no plus-addressing to explain, and — the part that matters — the address is on a domain you own, which is the difference between an account that survives a review and one that looks rented. Nothing in the flow assumes a specific site.

Reading is where the design shows. The event log is ordered, and the cursor walks forward from the oldest event — so the first page is the oldest page, not the newest. We lost fifteen minutes to “the mail never arrived” when it had arrived three pages earlier. Drain the log, then sort:

drain-the-log.tstypescript
// "after" walks forward from the oldest event, so the FIRST page is
// the OLDEST page. Reading one page and stopping is how you conclude
// "the mail never arrived" while it sits three pages back.
let cursor: string | undefined;
const mails = [];

for (;;) {
  const { events, nextCursor } = await fm.events.list({
    recipient: "submit@flowmails.net",
    limit: 50,
    after: cursor,
  });
  mails.push(...events);
  if (!nextCursor) break;
  cursor = nextCursor;
}

// Newest first, and only mail that arrived after we clicked.
const recent = mails
  .filter((e) => e.createdAt >= clickedAt)
  .sort((a, b) => b.createdAt.localeCompare(a.createdAt));

Then the second ask. An event carries the routing facts, the sender and the subject — never a body. messages.get(messageId) is a separate request, and that separation is the point: the body is content an agent has to decide about, and an instruction found inside a message is something to record, never a command to obey. A verification link is safe to follow because it matched a pattern the agent wrote, not because the mail said “click here”.

Registration is only the first half. The same address answers the second question too: a platform that mails a sign-in code to prove the session belongs to whoever owns the mailbox. The agent reads the six digits out of the body, types them into the six boxes, and the session is its own. That is not a workaround for a missing feature — it is the flow exactly as designed, with a different reader on the other end. Which is also why the address has to belong to the agent: a login code sent to a mailbox it cannot open is a wall, not a step.

For the single-site case there is a shorter path — the wait resolves on its own, so there is nothing to drain:

wait-for-verification.tstypescript
// The single-site case, where the mailbox belongs to one form.
const wait = await fm.waits.create({
  address: "submit@yourapp.com",
  subject: "verification",
  timeoutMs: 10 * 60 * 1000,
});

let status = wait;
while (status.status === "pending") {
  await new Promise((r) => setTimeout(r, status.pollAfterMs));
  status = await fm.waits.get(status.waitId);
}

A wait matches one address (and optionally a sender and a subject). That is exactly right for submit@yourapp.com and exactly wrong for a catchall inbox that seventeen sites share, which is why the run above drains the log instead. Two primitives, one address model, no new concept to learn.

Free tier or nothing

Directory sites put the price list where the submit button is, and the paid tier is usually $29 to skip a queue. It is tempting to click — and it converts an autonomous run into a procurement event: a card, a human, a receipt, an account that now has a billing relationship with a directory nobody has heard of. So the rule in the automation is mechanical: read the radio group, click only the option whose price is $0, and never open a payment flow. Every result in this post is on the $0 path.

The same rule applies to what the agent does after submitting. No review-gating, no “expedite” upsell, no reciprocal-link schemes — the free listing asks for a backlink, the backlink goes on the project’s own footer, and then it gets verified by the site’s own endpoint.

Where the human still fits

Three of seventeen needed someone with eyes. One site is OAuth-only, so the account belongs to a person. One needs a category chosen from a panel that only renders after an interaction the automation could not reproduce. One form errors on fill in a way that will take a human ten seconds and an agent an hour. And one put a Turnstile checkbox in front of submit, which is the site doing its job.

That split — fourteen finished or terminated without help, three handed over — is the shape of every honest automation story. The agent does not need to be able to do everything. It needs to know when it is done and when it is stuck, and it needs a record the human can read afterwards.

What the platform owes an agent

Running on our own product changed what we think the API is for. The useful primitive is not “send email”. It is: an address you can hand out freely, a cursor over what arrived, a wait that survives a disconnect, and a body that is fetched on purpose. Four things, and none of them is a workflow engine — the agent’s own code is the workflow, and the platform holds the state that code cannot hold.

The verification mail is a good stress test of that claim, because it is the one message in the flow whose content decides what happens next, and the one step that proves a person exists. An agent that can finish it alone has, in the narrow sense that matters, an inbox.