Quickstart
Every list and every form is one URL that accepts a POST. There is no SDK to install and no key to send — paste a snippet, submit it, and the record is in your dashboard before you switch tabs.
Your endpoint
Creating a project provisions its first list, and every list and form after that gets its own ID. The prefix tells you which kind it is: lst_ for a list, frm_ for a form.
POST https://api.mailcollectly.com/c/lst_a495balst_a495ba is a live sandbox endpoint — run any example on this page exactly as printed and it will answer for real. Swap in your own ID from the dashboard when you’re ready to keep what you collect.
It takes 200 submissions a day and anything it stores is deleted after seven days — a real endpoint with a small allowance and a retention rule, which is all any endpoint is. Send test data, not anyone’s actual address.
Paste one of these
The dashboard generates all four for your own endpoint. The HTML and React snippets carry the two spam fields described below; leave them exactly as they are and the spam stack protects you from the first submission onward.
<form method="POST" action="https://api.mailcollectly.com/c/lst_a495ba">
<label>
Email
<input type="email" name="email" required>
</label>
<!-- Spam protection. Leave both of these exactly as they are. -->
<input type="text" name="_hp" tabindex="-1" autocomplete="off"
aria-hidden="true" style="position:absolute;left:-9999px">
<input type="hidden" name="_ts" value="">
<button type="submit">Subscribe</button>
</form>
<script>
// Stamps when the form rendered, so submissions that arrive in under two
// seconds can be recognised as automated.
document.currentScript.previousElementSibling
.querySelector('input[name="_ts"]').value = Date.now();
</script>What you can send
Send whatever your form collects. email and name get their own columns; everything else is stored as JSON on the record and appears as a column in the records table.
| Field | Required | What it does |
|---|---|---|
| Lists only | Validated for syntax, checked against a disposable-domain list, and lowercased. A repeat address on the same list answers 200 and stores nothing new — it costs you no allowance. | |
| name | No | Stored in its own column, so exports stay tidy. |
| anything else | No | Stored as JSON on the record. Up to 100 fields, 10,000 characters each. File uploads are ignored — this is an audience tool, not a file host. |
| _hp | No | The honeypot. Rendered hidden; humans never fill it. Any value means the submission is quietly discarded. |
| _ts | No | When the form rendered, in ms or seconds. Submissions under two seconds old are quietly discarded. Missing stamps pass — curl has no render time. |
| _redirect | No | Where to send a plain HTML form after success. Relative paths, or absolute URLs on a domain the endpoint already allows. |
| cf-turnstile-response | If enabled | The Turnstile token, when the endpoint has a captcha switched on. |
_hp, _ts, _redirect and cf-turnstile-response are plumbing. They are stripped before the record is written, so they never show up in your data or your CSV.
Content types
- application/json — a flat object. Numbers and booleans are coerced to text; nested objects keep their shape as JSON.
- application/x-www-form-urlencoded — what a plain HTML form posts.
- multipart/form-data — forms with a file input. Text fields are kept, files are dropped.
A body with no recognisable content type is parsed as URL-encoded, because that is what a bare form sends when something strips the header. A body that can’t be read at all returns 400 invalid_request rather than failing silently.
What comes back
Success is the same shape for a stored record, a repeat signup, and a bot caught by the honeypot. That is deliberate: a bot that learns it was caught is a bot that adapts.
{
"success": true
}Plain HTML forms have nowhere to put a JSON body, so a form-encoded POST that sends Accept: text/html and a _redirect gets a 303 to that page instead. Everything else gets JSON.
Refusals are never bare status codes. Each one names the limit, says where you stand, and links to the way out — all of them are documented.