Framework guides

Add a contact form to a Hugo site

Hugo builds plain HTML files, so there's nothing on your host to receive a form. A partial that posts to embedio fixes that, and keeping the form key in your site config means one change updates every page that uses it.

1. Create the form in embedio

Sign up (the Free plan includes 500 submissions a month and needs no card), create a form, and copy its key. It looks like frm_ followed by ten characters. Everywhere below, replace frm_your_form_key with yours.

The form key is meant to be public: it only lets people submit to that one form, never read anything. It's safe in client-side code and in your repository.

2. Add the key to your config

hugo.toml

[params]
  embedioEndpoint = "https://api.tryembedio.com/f/frm_your_form_key"

3. Create the partial

layouts/partials/contact-form.html

<form action="{{ site.Params.embedioEndpoint }}" method="POST">
  <label for="email">Email</label>
  <input id="email" type="email" name="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" required></textarea>

  <!-- Honeypot: hidden from people, filled in by bots -->
  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">

  <!-- Where to send people after a successful submit (same site) -->
  <input type="hidden" name="_redirect" value="{{ "thanks/" | relURL }}">

  <button type="submit">Send</button>
</form>

Include it from any template with {{ partial "contact-form.html" . }}, and create content/thanks.md for the page people land on afterwards.

4. Optional: a shortcode for Markdown pages

To drop the form into a Markdown page such as content/contact.md, wrap the partial in a shortcode:

layouts/shortcodes/contact-form.html

{{ partial "contact-form.html" .Page }}

Then write {{< contact-form >}} wherever the form should appear.

Spam and validation

Honeypot: a hidden _gotcha field. People never see it; bots that fill it get a normal-looking success and nothing is stored.
Double clicks: an identical submission seconds after the first is dropped instead of stored twice.
Trust level: each form has a relaxed, balanced or strict setting for bursts and repeated content. Flagged submissions are kept aside for review, not deleted.
Server-side rules: validations such as required, email or max length run on embedio, so they hold even if someone skips your front end.

Getting notified

Every submission shows up in your dashboard straight away. To also get an email for each one, add an Email connection to the form; that works on every plan, including Free. Slack, Discord, Zapier, webhooks and the other connections come with any paid plan, from $9/mo.

Errors you might see

With a JSON request, every failure comes back as a status code plus { "error": "..." }. A plain HTML post gets a readable error page instead.

Status	error	What it means
404	`form_not_found`	The form key is wrong or the form was deleted.
422	`validation_failed`	A validation rule failed; `fields` lists `{ field, message }` for each one.
402	`monthly_limit_reached`	The account used its submissions for the month.
413	`file_too_large`	An uploaded file is over 10MB.
400	`invalid_file_type`	The file type isn't accepted (images, PDF, Office documents, TXT and CSV are).
429		More than 20 submissions a minute from one IP address. Wait and retry.

The full list, including module-specific errors, is in the API reference.