Connect a form

Quickstart

Create a form from your workspace to get its public access key, then paste the snippet into any page on the website address you registered. The form is live straight away.

<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>

Request format

Send a POST to https://submit.heartdove.com/v1/submit as JSON or as a regular form post.

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 } }

Receipts

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

HTTP/1.1 202 Accepted

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

Browsers posting a plain HTML form receive a simple confirmation page instead of JSON, or are sent to your own thank-you page when the form includes _redirect.

Errors and retries

Every error returns { success: false, error: { code, message, retryable } }. Retry only when retryable is true, with the same idempotency key, and a fresh Turnstile token if the form uses one.

JavaScript SDK

The typed client wraps the request, validates every response, keeps the idempotency key across retries and, for forms that use Turnstile, asks for a fresh token on each attempt through getToken. client.begin(fields) returns an attempt you can retry after a network failure without creating a second submission.

Framework adapters

The React hook, Vue directive and Svelte action share one controller, so behaviour and states are identical across frameworks. Each has been mounted in its real runtime and posted end to end, including through Turnstile.

import { createClient, readForm } from '@heartdove/forms';
import { useFormSubmit } from '@heartdove/forms/react';

const client = createClient({
  endpoint: 'https://submit.heartdove.com/v1/submit',
  accessKey: 'YOUR_ACCESS_KEY',
});

export function Contact() {
  const { state, submit } = useFormSubmit(client);
  return (
    <form onSubmit={e => { e.preventDefault(); submit(readForm(e.currentTarget).fields); }}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button disabled={state.phase === 'submitting'}>Send message</button>
    </form>
  );
}

Platforms and site builders

Every platform sends the same request: the HTML snippet or a fetch call. The form must be served from the origin you registered, because Heartdove checks it exactly. Plain HTML and the React, Vue and Svelte adapters have been tested in real browsers; the rows below describe where the same snippet goes on each platform.

Signed webhooks

Webhook destinations receive submission.created events. Each request carries:

import { createHmac, timingSafeEqual } from 'node:crypto';

// Verify the raw body before parsing it. Reject anything older than five minutes.
export function verifyHeartdove(rawBody, headers, secret) {
  const timestamp = headers['x-heartdove-timestamp'];
  const signature = headers['x-heartdove-signature'] ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

// Deduplicate on the X-Heartdove-Id header: delivery is at least once.

Redirects are never followed and a non-2xx response is retried with backoff. Destinations must use an operator-approved HTTPS hostname. Questions? Read how Heartdove protects data.