Formspree

https://help.formspree.io/
Admin
Formspree is a form backend service and API that allows developers to collect HTML and React form...
Tokens:86,687
Snippets:958
Trust Score:7.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install @formspree/react

Source: https://help.formspree.io/articles/using-the-cli/build-a-mailchimp-form-with-react.md

Install the React helper library for Formspree in your project.

```bash
npm install @formspree/react
```

--------------------------------

### Install and Initialize Formspree CLI

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Run these commands to install the Formspree CLI globally and initialize a new project. This creates an empty formspree.json file in the project root.

```shell
npm i -g @formspree/cli
formspree init
```

--------------------------------

### Example formspree.json Configuration

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Example configuration for a newsletter sign-up form that adds subscribers to a Mailchimp list. The apiKey references an environment variable using $ notation.

```javascript
{
  "forms": {
    "signupForm": {
      "name": "Sign-Up Form",
      "actions": [{ 
        "app": "mailchimp", 
        "type": "addOrUpdateContact", 
        "apiKey": "$FORMSPREE_MAILCHIMP_APIKEY" 
      }]
    }
  }
}
```

--------------------------------

### Install Formspree CLI

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Install the Formspree CLI globally using npm.

```shell
npm i -g @formspree/cli
```

--------------------------------

### Install @formspree/ajax via npm or yarn

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Use these commands to add the library to your project when using a bundler.

```bash
npm install @formspree/ajax   # via npm, or
yarn add @formspree/ajax      # via yarn
```

--------------------------------

### Example formspree.json file

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-json-file.md

A complete example of a formspree.json file with a contact form, including captcha, fields, and an email action.

```javascript
{
  "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" }
      ]
    }
  }
}
```

--------------------------------

### formspree.json Airtable action example

Source: https://help.formspree.io/articles/using-the-cli/send-submissions-to-airtable.md

Example configuration for the Formspree CLI to send submissions to Airtable. Add this action to the formspree.json file. The apiKey references an environment variable $AIRTABLE_API_KEY. The syncSubmissions option is optional and defaults to false.

```json
{
    "forms": {
      "wedding": {
      "name": "Wedding presence confirmations",
      "actions": [
          {
          "app": "airtable",
          "type": "sendToTable", 
          "apiKey": "$AIRTABLE_API_KEY",
          "baseName": "Wedding",
          "tableName": "Confirmed guests",
          "syncSubmissions": true
        }
      ]
    }
  }
}
```

--------------------------------

### Sample Submissions Response

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Example JSON response showing the structure of the submissions data, including fields and submission objects.

```json
{
  "fields": [
    "_date", 
    "email", 
    "message",
    "_status"
  ], 
  "submissions": [
    {
      "_date": "2018-11-03T07:28:29.707632", 
      "email": "myemail@example.com", 
      "message": "asdfasdf",
      "_status": {
        "my@email.com": {
          "delivered": true,
          "processed": true,
          "dispatched": true
        },
        "plugin:discord": {
          "processed": true
        }
      }
    },
    ...
  ]
}
```

--------------------------------

### Fetch Submissions with cURL

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Example cURL command to fetch all submissions. Uses the API key as the username with an empty password.

```bash
curl -u :API_KEY https://formspree.io/api/0/forms/<hashid>/submissions
```

--------------------------------

### GitHub Actions deploy workflow

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Example GitHub Actions step that sets environment variables from secrets and runs formspree deploy.

```yaml
steps:
  - shell: bash
    env: 
      - FORMSPREE_DEPLOY_KEY: ${{ secrets.FormspreeDeployKey }}
      - FORMSPREE_MAILCHIMP_APIKEY: ${{ secrets.MailchimpAPIKey }}
    run: formspree deploy
```

--------------------------------

### Filter Submissions by Date

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Use the 'since' parameter to get submissions after a specific ISO date.

```bash
curl https://formspree.io/api/0/forms/<hashid>/submissions?since=2018-11-03T12:00:00
```

--------------------------------

### Initialize useForm hook

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Call useForm with the form key from formspree.json to get state and handleSubmit for form management.

```jsx
const [state, handleSubmit] = useForm('{form-key}');
```

--------------------------------

### Wrap Next.js app with FormspreeProvider

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Example of a top-level _app.js file in Next.js that wraps the app with FormspreeProvider, supplying the project ID obtained from the dashboard.

```jsx
import { FormspreeProvider } from '@formspree/react';

function App({ Component, pageProps }) {
  return (
    <FormspreeProvider project="YOUR_PROJECT_ID">
      <Component {...pageProps} />
    </FormspreeProvider>
  );
}
export default App;
```

--------------------------------

### Example field rules configuration

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-json-file.md

Shows a complete Formspree form configuration with field validation rules for email, birthdate, and document fields. Includes type, required, min, max, and contentType properties.

```javascript
{
  "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 */
        }
      }
    }
  }
}
}
```

--------------------------------

### Webhook action configuration in formspree.json

Source: https://help.formspree.io/articles/using-the-cli/send-a-webhook.md

Configure a webhook action in the formspree.json file. The 'type' must be 'webhook' and 'url' is required. This example sends a POST request to http://example.com/hook.

```json
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "type": "webhook",
          "url": "http://example.com/hook"
        }
      ]
    }
  }
}
```

--------------------------------

### JSON export example

Source: https://help.formspree.io/articles/form-and-project-settings/exporting-submissions.md

Shows the structure of a JSON export from Formspree, including email, fields, host, and submissions properties. Use this to understand the format when parsing exported data.

```javascript
{
    "email": [
        "team@formspree.io",
        "support@formspree.io"
    ],
    "fields": [
        "email",
        "message"
    ],
    "host": null,
    "submissions": [
        {
            "email": "emily@formspree.com",
            "message": "Formspree is awesome!"
        }
    ]
}
```

--------------------------------

### Create .env.example template

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Create a .env.example file with the deploy key variable name as a template for other developers.

```shell
echo "FORMSPREE_DEPLOY_KEY=" >> .env.example
```

--------------------------------

### Set up .env file

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Create a .env file with the deploy key and add it to .gitignore to avoid committing secrets.

```shell
echo "FORMSPREE_DEPLOY_KEY=<your-deploy-key>" >> .env
echo ".env" >> .gitignore
```

--------------------------------

### Run a local web server with Python (Mac/Linux)

Source: https://help.formspree.io/articles/troubleshooting/unable-to-submit-form-error.md

Use this command to start a simple HTTP server on port 8000 when testing forms locally. This is necessary because opening HTML files directly via file:// does not send the referer header, causing the 'Unable to submit form' error.

```bash
python -m SimpleHTTPServer 8000
```

--------------------------------

### Custom field example

Source: https://help.formspree.io/articles/plugins/use-activecampaign-to-collect-contacts.md

Send custom field values by matching submission keys to ActiveCampaign custom field titles (case-insensitive, spaces ignored). This example matches a custom field titled "Company Size".

```html
<input type="text" name="companysize" placeholder="Company Size">
```

--------------------------------

### formspree.json configuration for Pipedrive create lead

Source: https://help.formspree.io/articles/using-the-cli/create-leads-in-pipedrive.md

Example configuration for the create lead action in formspree.json. The apiKey must be an environment variable reference. The value and currency fields are optional and only used when variableLeadValue is false.

```json
{
  "forms": {
    "salesForm": {
      "name": "Sales Form",
      "actions": [
        {
          "app": "pipedrive",
          "type": "createLead",
          "apiKey": "$apiKey",
          "overwriteContact": true
          "variableLeadValue": false,
          "value": 100,
          "currency": "EUR"
        }
      ]
    }
  }
}
```

--------------------------------

### Initialize form with script tag

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Use this snippet before the closing body tag if you are not using a bundler.

```html
<script>
  window.formspree =
    window.formspree ||
    function () {
      (formspree.q = formspree.q || []).push(arguments);
    };
  formspree(
    'initForm', 
    { formElement: '#contact-form', formId: 'YOUR_FORM_ID' }
  );
</script>
<script src="https://unpkg.com/@formspree/ajax@1" defer></script>
```

--------------------------------

### Form component using useForm hook

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Example form component using the useForm hook from @formspree/react.

```jsx
import { useForm } from '@formspree/react';

function MyForm() {
  const [state, handleSubmit] = useForm('{your-form-key}');
  if (state.succeeded) {
    return <div>Thank you for signing up!</div>;
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" />
      <button type="submit" disabled={state.submitting}>Sign up</button>
    </form>
  )
}
```

--------------------------------

### GET /api/0/forms/<hashid>/submissions

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Fetch all submissions for a form. Supports filtering via query parameters.

```APIDOC
## [GET] https://formspree.io/api/0/forms/<hashid>/submissions

### Description
Fetch all your submissions.

### Method
GET

### Endpoint
https://formspree.io/api/0/forms/<hashid>/submissions

### Parameters
#### Path Parameters
- **hashid** (string) - Required - The form's hashid.

#### Query Parameters
- **since** (string) - Optional - Get all submissions since a date. Dates must be ISO formatted, such as `2018-11-03T12:00:00`.
- **limit** (integer) - Optional - Limit the number of results.
- **offset** (integer) - Optional - Cursor in pagination. Frequently used in conjunction with limit.
- **order** (string) - Optional - Change the order. By default the order is `desc`.
- **spam** (boolean) - Optional - Return messages that have been flagged or marked as spam. By default this value is `false`.

### Request Example
```bash
curl -u :API_KEY https://formspree.io/api/0/forms/<hashid>/submissions
```

### Response
#### Success Response (200)
- **fields** (array of strings) - List of field names.
- **submissions** (array of objects) - List of submission objects.

#### Response Example
```json
{
  "fields": [
    "_date",
    "email",
    "message",
    "_status"
  ],
  "submissions": [
    {
      "_date": "2018-11-03T07:28:29.707632",
      "email": "myemail@example.com",
      "message": "asdfasdf",
      "_status": {
        "my@email.com": {
          "delivered": true,
          "processed": true,
          "dispatched": true
        },
        "plugin:discord": {
          "processed": true
        }
      }
    }
  ]
}
```
```

--------------------------------

### Before migration: StaticKitProvider in Next.js

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Original Next.js file using StaticKitProvider with a site prop.

```jsx
import { StaticKitProvider } from '@statickit/react';

function App({ Component, pageProps }) {
  return (
    <StaticKitProvider site="{your-site-id}">
      <Component {...pageProps} />
    </StaticKitProvider>
  );
}

export default App;
```

--------------------------------

### formspree.json configuration for Freshdesk createSupportTicket

Source: https://help.formspree.io/articles/using-the-cli/create-support-tickets-in-freshdesk.md

Configuration example for the create support ticket action in formspree.json. Requires an apiKey as a $env variable reference and a subdomain without .freshdesk.com or https. The action implicitly validates that email is required and of type email, and that message or msg is required.

```javascript
{
  "forms": {
    "support": {
      "name": "Support Form",
      "actions": [
        {
          "app": "freshdesk",
          "type": "createSupportTicket",
          "apiKey": "$FRESHDESK_APIKEY"
          "subdomain": "newaccount1612001078242"
          
        }
      ]
    }
  }
}
```

--------------------------------

### formspree.json configuration for Gorgias createSupportTicket

Source: https://help.formspree.io/articles/using-the-cli/create-support-tickets-in-gorgias.md

Example configuration for the formspree.json file that adds a create support ticket action for Gorgias. Requires the app to be 'gorgias', type 'createSupportTicket', and the apiKey must be a $env variable reference. The subdomain and email are also required.

```json
{
  "forms": {
    "support": {
      "name": "Support Form",
      "actions": [
        {
          "app": "gorgias",
          "type": "createSupportTicket",
          "apiKey": "$GORGIAS_APIKEY",
          "subdomain": "testformspree",
          "email": "test@formspree.io"
        }
      ]
    }
  }
}
```

--------------------------------

### Get Submissions Endpoint

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Retrieves all form submissions. Requires an authenticated request with your API key and the form's hashid.

```http
GET https://formspree.io/api/0/forms/<hashid>/submissions
```

--------------------------------

### Initialize form with ESM

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Import and initialize the form using the initForm function when working with a bundler.

```javascript
import { initForm } from '@formspree/ajax';

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',
});
```

--------------------------------

### HTML input with duplicate name attribute

Source: https://help.formspree.io/articles/troubleshooting/i-m-receiving-an-invalid-replyto-email-error.md

First example of an input with name="email" that contributes to the duplicate-name error.

```html
<input type="text" name="email" id="email">
```

--------------------------------

### useForm with data option

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Example of using the data option to merge custom data into the form submission. The pageTitle function is evaluated at submission time.

```jsx
const [state, handleSubmit, reset] = useForm('{your-form-id}', {
  data: {
    subject: 'Someone joined the newsletter',
    pageTitle: function() {
      // This function will be evaluated at submission time
      return document.title;
    }
  }
});
```

--------------------------------

### Deploy Formspree Configuration

Source: https://help.formspree.io/articles/using-the-cli/build-a-mailchimp-form-with-react.md

Deploy your form configuration changes to Formspree using the CLI.

```bash
formspree deploy -k <your-deploy-key>
```

--------------------------------

### formspree.json with Mailchimp action

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-json-file.md

Example of a formspree.json file that configures a Mailchimp action for a contact form, using the addOrUpdateContact type and an API key from an environment variable.

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

--------------------------------

### Example of resubmitting the form

Source: https://help.formspree.io/articles/plugins/use-stripe-to-accept-payments-with-sca.md

Shows how to resubmit the form to Formspree after Stripe SCA validation. Sends the payment intent ID and resubmit key in the request body.

```javascript
function resubmitForm(result, resubmitKey) {
  console.log("handle Stripe SCA result");
  if (result.error) {
    // Show error in payment form
    console.log("Stripe SCA error");
  } else {
    // The card action has been handled
    // The PaymentIntent can be confirmed again on the server
    fetch('https://formspree.io/f/', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 
        paymentIntent: result.paymentIntent.id ,
        resubmitKey: resubmitKey,
        email: 'jenny@rosen.com',
      })
    }).then(function(result) {
      return result.json();
    }).then(handleServerResponse);
  }
}
```
Tokens:
Raw