Connecting your site to an Inbox

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Astro

Bridgetown

Docusaurus

Eleventy

Gatsby

Hugo

Jekyll

Lume

MkDocs

Next.js

Nuxt

Static

SvelteKit

Custom

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

To receive form submissions from your sites, you first need to connect your site to an Inbox in CloudCannon.

To connect your site to an Inbox:

1. Navigate to the forms menu in your site settings, under Hosting > Forms.
2. In the Link Inbox menu, select the Inbox you want to link.
3. At this point, you can also toggle the visibility of the Inbox on your site with the Display Inbox option. You can also require a CAPTCHA for submissions from this site with the Require CAPTCHA option. See here for more information about using CAPTCHA for your Inbox.
4. Click Link Inbox to finish linking the Inbox to your site.

Now create a form on your site and configure it to submit to one of your connected Inboxes.

To create a form:

1. Add an HTML form to a page.
2. Set the method attribute to post.
3. Set the action to the URL to redirect the visitor to after they submit the form.
4. Add an input element with the name inbox_key and set its value attribute to the key you gave your Inbox. If you don’t include this input, the submission will be sent to the default Inbox connected to your site.
5. Add form fields with name attributes to collect additional data from visitors.
6. If you are adding captcha to prevent spam, follow the documentation (Google reCAPTCHA or hCaptcha) to add the required code to your form. 

<form method="post" action="/success.html">
  <label>Email Address</label>
  <input type="text" name="email">

  <label>Name</label>
  <input type="text" name="name">

  <label>Message</label>
  <textarea name="message"></textarea>

  <label>Urgent</label>
  <input type="checkbox" name="urgent">

  <input type="hidden" name="inbox_key" value="your-inbox-key">
  <input type="text" name="_gotcha" style="display: none;">

  <input type="submit" value="Send Message">
</form>

Special Fields#

Any CloudCannon form can use the _gotcha field to help prevent untargeted spam. CloudCannon does not accept a submission if this field has a value. Hide it with CSS to prevent visitors from filling it out.

<input type="text" name="_gotcha" style="display: none;">

Receiving files through your forms#

You can also use CloudCannon Forms to receive file uploads from visitors to your site.

To setup file uploads on your form:

1. Set your form’s enctype attribute to multipart/form-data
2. Add an input element to your form with the type attribute set to file

<form action="/" enctype="multipart/form-data" method="post">
  <input accept="image/png, image/jpeg" id="avatar" name="avatar" type="file">
  <input type="submit" value="Send Message">
</form>

Now when visitors to your site submit a file through your form, CloudCannon will save that file and then replace it with a link that you can use to access the file.

Limitations#

File submissions through CloudCannon have the following limitations:

• Each file must be smaller than 5Mb in size.
• At most 5 files can be submitted at a time.
• Each non-file field must be smaller than 10kb in size.
• At most 100 non-file fields can be submitted at a time.

Submitting with JavaScript#

Submitting a form with JavaScript saves a page load after sending a message, providing a seamless experience. Viewers without JavaScript enabled will fall back to the normal flow.

To submit your form with JavaScript:

1. Build and test your form.
2. Override the submit event on your form.
3. Change the page to notify your viewers the message was sent.

Start with this JavaScript snippet and adapt it for your site:

// Helper function to get form data in the supported format
function getFormDataString(formEl) {
    var formData = new FormData(formEl),
      data = [];

  for (var keyValue of formData) {
      data.push(encodeURIComponent(keyValue[0]) + "=" + encodeURIComponent(keyValue[1]));
  }

  return data.join("&");
}

// Fetch the form element
var formEl = document.getElementById("contact-form");

// Override the submit event
formEl.addEventListener("submit", function (e) {
    e.preventDefault();

  if (grecaptcha) {
      var recaptchaResponse = grecaptcha.getResponse();
    if (!recaptchaResponse) { // reCAPTCHA not clicked yet
      return false;
    }
  }

  var request = new XMLHttpRequest();

  request.addEventListener("load", function () {
    if (request.status === 303) { // CloudCannon redirects on success
      // It worked
    }
  });

  request.open(formEl.method, formEl.action);
  request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
  request.send(getFormDataString(formEl));
});