A contact form API that proves delivery.

The endpoint

Send a POST to https://submit.heartdove.com/v1/submit as a regular form post or as JSON. The request must come from a website address registered on the form: the browser sends that Origin header automatically, and a server-side call has to set it. The endpoint answers CORS preflights, so fetch from your page works without a proxy.

From an HTML form

The simplest client is the browser itself. The visitor gets a confirmation page, or your own page if the form sets _redirect.

<form action="https://submit.heartdove.com/v1/submit" method="POST">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY" />
  <label>Email <input type="email" name="email" required /></label>
  <label>Message <textarea name="message" required></textarea></label>
  <!-- Hidden spam trap: people never see it, bots tick it -->
  <input type="checkbox" name="botcheck" tabindex="-1" autocomplete="off" style="display:none" />
  <button type="submit">Send message</button>
</form>

From JavaScript

Post JSON to stay on the page. Generate the idempotency key once per message and reuse it for retries.

const response = await fetch('https://submit.heartdove.com/v1/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry
  },
  body: JSON.stringify({
    access_key: 'YOUR_ACCESS_KEY',
    // turnstile_token: token, // only if the form uses Cloudflare Turnstile
    fields: { email, message },
  }),
});

const receipt = await response.json();
// 202 { success: true, data: { id, status: 'accepted', duplicate: false } }

Try it with curl

Set the Origin header to one of the form’s registered addresses; without it the request is refused with origin_not_allowed.

curl -X POST https://submit.heartdove.com/v1/submit \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.yourdomain.com" \
  -H "Idempotency-Key: 6c1f2d0e-8e1b-4d7e-9a0b-3f2c1d4e5f60" \
  -d '{"access_key":"YOUR_ACCESS_KEY","fields":{"email":"alex@example.com","message":"Hello from curl"}}'

The receipt

A 202 means the submission is stored. It is a capture receipt, not proof that the email arrived; delivery appears on the message timeline in your inbox. A retry with the same idempotency key returns 200 with duplicate: true and the original ID.

HTTP/1.1 202 Accepted

{
  "success": true,
  "data": {
    "id": "83841cff-c4f9-4901-9167-8e9fd559c990",
    "status": "accepted",
    "duplicate": false
  }
}

Errors and retries

Every error returns { success: false, error: { code, message, retryable } }. Retry only when retryable is true, with the same idempotency key. The full list, including Turnstile and redirect codes, is in the docs.

After the receipt: delivery you can see

The API’s job ends at the receipt, but the message’s does not. Each submission in your inbox shows its own timeline: captured, accepted by the email provider, then delivered or bounced with the reason. A bounced address is paused and flagged. Signed webhooks carry the same submission to your systems with a timestamped HMAC signature and a stable event ID; see verifying webhooks.

The typed client

@heartdove/forms wraps the request, validates every response, keeps the idempotency key across retries and asks for a fresh Turnstile token on each attempt when a form uses one. Adapters for React, Vue and Svelte share one controller. The package ships with the Heartdove source and is not yet published to npm.

Questions

Keep reading

• Full documentation
• Send an HTML form to email
• What is a form backend?
• How submissions are protected