The formspree.json File

The formspree.json file is where you can create and configure forms for a website. For example, you can create opt-in forms for a Mailchimp list, or contact forms that email you when submitted. The formspree.json file is used by the Formspree CLI when deploying your forms to the Formspree servers.

Form Configuration

Forms accept the following config parameters:

Property	Type	Default	Description
name	String		The name of the form (required)
actions	Array	[]	An Array of actions to perform after submission
fields	Object	{}	Optional metadata about form fields
captcha	Object	{}	Optional captcha settings.

Captcha object should follow this format:

"captcha": {
    "type": "recaptcha",                  // Required
    "recaptchaSecret": "my-secret"        // Optional
}

Example Here’s an example formspree.json file:

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "captcha": {
        "type": "recaptcha",
        "recaptchaSecret": "my-secret"
      },
      "fields": {
        "email": { "type": "email", "required": true },
        "message": { "type": "text", "required": true }
      },
      "actions": [
        { "type": "email", "to": "john@example.com" }
      ]
    }
  }
}

Post-Submit Actions

Forms accept an array of actions to perform after submission. We have a few built-in actions and a growing list of integrations with other apps:

App	Type	Description
	email	Sends a notification email. Read more
	autoresponse	Sends a response to the submitter. Read more
	webhook	Sends a webhook to a given url. Read more
mailchimp	addOrUpdateContact	Create subscribers in Mailchimp. Read more
mailerlite	addSubscriber	Add subscribers to MailerLite. Read more
convertkit	applyTags	Create subscribers and apply tags in ConvertKit. Read more
hubspot	createContact	Create contacts in Hubspot. Read more
freshdesk	createSupportTicket	Create tickets in Freshdesk. Read more
zendesk	createSupportTicket	Create tickets in Zendesk. Read more
airtable	sendToTable	Add rows in Airtable. Read more
trello	createCard	Create cards in Trello. Read more
discord	sendMessage	Send messages to Discord. Read more
gorgias	createSupportTicket	Create tickets in Gorgias. Read more

Here’s an example of a formspree.json file with a Mailchimp action:

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "app": "mailchimp",
          "type": "addOrUpdateContact",
          "audience": "8djs8fg8d",
          "apiKey": "$MAILCHIMP_APIKEY"
        }
      ]
    }
  }
}

Field Rules

You can optionally configure which fields are allowed, the type they should be, and various validation rules for them.

Note: By default, Formspree will accept any fields you pass in from the client-side. However, defining your fields here allows you to add validations (such as marking a field as required) and give them human-friendly names.

Field objects can contain the following properties:

Key	Type	Description
required	Boolean	Specifies whether the field is required
type	String	The field type. One of text, email, numeric, datetime-local, url or file.
min	Number or String	Specifies the minimum value. This can be used with numeric, datetime-local or file types. Be aware that you should specify the field type otherwise this rule won’t be applied.
max	Number or String	Specifies the maximum value. This can be used with numeric, datetime-local or file types. Be aware that you should specify the field type otherwise this rule won’t be applied.
minlength	Number	Specifies the minimum value. This can be used with text, url or email types. Be aware that you should specify the field type otherwise this rule won’t be applied.
maxlength	Number	Specifies the maximum value. This can be used with text, url or email types. Be aware that you should specify the field type otherwise this rule won’t be applied.
accept	String list	Specifies valid file content types. The value should be a string list with valid MIME types. Be aware that you should set the type key as file otherwise, this rule won’t be applied.

**Notes:
**The datetime-local type accepts ISO formats. The default format is yyyy-mm-dd hh:mm:ss. This type also accepts dates only, for example yyyy-mm-dd. For more information, check this.

The min and max values for file types are the minimum and maximum file sizes in MiB.

Example

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "fields": {
        "email": {
          "type": "email",
          "required": true
        },
        "birthdate": {
          "type": "datetime",
          "required": true,
          "min": "2002-09-21 13:13:00"        /* also accept dates */
        },
        "document": {
          "type": "file",
          "contentType": ["application/pdf"],  /* please use valid MIME Types */
          "min": 10                            /* MiB */
        }
      }
    }
  }
}