Contact form setup

What Free and Pro can do

Free projects can use contact forms and receive submissions. They send email notifications from the standard Handover sender only.

Pro workspaces can add reusable sender accounts in account settings. A project contact form can then choose one of those sender accounts from a dropdown.

• Free: set recipient, subject prefix, heading, intro copy, and field schema
• Free: sender account control is locked and remains Handover managed sender
• Pro: add one or more verified Resend sender accounts in Settings
• Pro: choose a sender account per project contact form

1) Configure the project form

Open the project dashboard, go to Forms, then edit the Contact Form card. This is where the client site's actual form behavior is configured.

The target email is the inbox that receives notifications. The field schema controls what the generated site renders and what gets stored with each submission.

• Target email: where notifications are sent
• Subject prefix: the email subject prefix, for example Website enquiry
• Form heading and intro copy: text shown on the client site
• Field schema: JSON array of fields rendered by the starter form

[
  { "name": "name", "label": "Name", "type": "text", "required": true },
  { "name": "email", "label": "Email", "type": "email", "required": true },
  { "name": "message", "label": "Message", "type": "textarea", "required": true }
]

2) Choose the sender

In the Contact Form card, the Delivery sender section controls who the notification email appears to come from.

On Free, this is intentionally locked to Handover managed sender. On Pro, choose a sender account from the dropdown or use Handover managed sender as the fallback.

• Use Handover managed sender when you want the simplest setup
• Use a Pro sender account when the client needs mail from their own verified domain
• If a sender account is removed or invalid, delivery falls back instead of exposing credentials

3) Add a Pro sender account

Go to Settings, then Email sender accounts. Add a name, a verified sender value, and a Resend API key.

The sender value must match a sender or domain already verified inside the Resend account whose API key you paste.

• Account name: a label like Acme website forms
• Verified sender: an email or display-name format like Website Forms <forms@example.com>
• Resend API key: stored encrypted and only shown later as a preview
• After saving, return to the project Contact Form card and select it

4) Connect the client site

Generated starters already know the contact form content keys. For custom sites, submit through the SDK or the HTTP forms endpoint.

Submissions are always stored first. Email delivery is attempted after storage, so a temporary email provider issue does not lose the message.

await handover.submitContactForm({
  senderName: form.name,
  senderEmail: form.email,
  message: form.message,
  fields: {
    budget: form.budget,
  },
});

Platform environment variables

These are platform-side Convex environment variables, not variables for the generated client site.

• RESEND_API_KEY enables Handover managed delivery
• HANDOVER_CONTACT_FROM_EMAIL optionally changes the managed sender address
• HANDOVER_EMAIL_SETTINGS_SECRET is required for Pro sender accounts and must be at least 32 characters

npx convex env set RESEND_API_KEY re_your_platform_key
npx convex env set HANDOVER_CONTACT_FROM_EMAIL 'Handover Forms <forms@handovertools.com>'
npx convex env set HANDOVER_EMAIL_SETTINGS_SECRET 'use-a-long-random-secret-at-least-32-chars'

Troubleshooting

Most contact form problems come from mixing up the recipient, the sender, and the client site API key. They are separate settings.

• No email, but submission exists: check RESEND_API_KEY or the selected Pro sender account
• Resend rejects the email: verify the sender domain in the same Resend account as the API key
• Free account cannot select sender: expected; upgrade to Pro or use Handover managed sender
• Client site cannot submit: check the site's HANDOVER API URL and API key env vars
• Wrong inbox receives messages: update Target email in the project Contact Form card