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 |
Example Here's an example formspree.json file:
{
"forms": {
"contact": {
"name": "Contact Form",
"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 or file. |
min |
Number or String | Specifies the minimum value. This can be used with numeric,text, datetime 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,text, datetime or file types. Be aware that you should specify the field type otherwise this rule won't be applied. |
contentType |
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 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.
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 */
}
}
}
}
}