Usage

If no users exist in the database, SnowMail will create a default user with the username admin and password snowmail. It is recommended to change the password immediately after login.

The SnowMail dashboard allows you to easily create contact forms which can be added to websites with a few lines of code.

Important

When creating your form, create a button with the type set to submit. Without this, users won't be able to submit the form unless you write additional code.

It is recommended to add your EMAIL_FROM address (configured during the installation process) to your contact list to reduce the chance of emails ending up in spam.

You'll need to install SnowMail from NPM (or use the CDN option):

npm install --save snowmail

The client-side (npm package) and server-side (Docker image/Java app) code are versioned independently.

Note

Having multiple contact forms on the same page is currently not supported.

Properties

The following properties are available to all usage methods below. Some methods may support (or require) additional properties.

interface Props {
  url: string
  id: string
  // Use the getForm method exported by api.js to get the inputs.
  inputs?: InputUnion[]
  // If you'd like to submit the form yourself, pass a handler function.
  handler?: (values: Record<string, any>) => Promise<HandlerReturnValue>
  /*
    Pass the `afterSubmit` function to run code after the form has submitted.
    This will disable scrolling to the top of the form after submission.
    Call the `scroll` function to scroll to the top of the form.
  */
  afterSubmit?: (scroll: () => void) => void
}

React

Minimum React version: v18.2.0

SnowMail requires Mantine (v7.8.1+) to be installed.

npm install --save @mantine/core @mantine/form

Then, import the ContactForm component:

import ContactForm from 'snowmail/react/ContactForm.jsx';
<ContactForm url="https://snowmail.example.com" id="6627b0113f4c7e0d773abc2b" />

You can also pass props to the MantineProvider using the providerProps prop.

If you'd like to server render SnowMail, you can pass the form definition to the inputs prop. Use the getForm method exported by api.js to get the form definition. It is recommended to set the data-mantine-color-scheme attribute on the html element to either light or dark when using SSR to ensure styles are applied before hydration.

Tip

Already using Mantine? Use the MantineContactForm component instead.

Astro

Astro doesn't support React contexts which are required for Mantine to work. Additionally, React bundle sizes are quite large which can slow down website loading times. To address both of these issues, SnowMail offers an Astro component which uses a pre-built Preact bundle instead.

import ContactForm from 'snowmail/astro/ContactForm.astro';
<ContactForm url="https://snowmail.example.com" id="6627b0113f4c7e0d773abc2b" />

To enable SSR, just add the ssr prop. It is recommended to set the data-mantine-color-scheme attribute on the html element to either light or dark when using SSR to ensure styles are applied before hydration.

Note

While it is possible to set the providerProps prop, the Astro component only supports properties that can be JSON serialized. If you need to pass a function property to providerProps, create your own component using the NPM method below.

If you use PurgeCSS, add the following to your config to prevent Mantine classes from being removed:

{
  safelist: {
    greedy: [/^m_/, /mantine/]
  }
}

Other

It is possible to use SnowMail on websites that don't use React or Astro by importing the pre-built Preact bundle.

NPM

<div id="snowmail"></div>
<script type="module">
  import 'snowmail/dist/main/styles.css';
  import { render } from 'snowmail/dist/main/index.mjs';
  render({
    element: document.getElementById('snowmail'),
    url: 'https://snowmail.example.com',
    id: '6627b0113f4c7e0d773abc2b',
    providerProps: {}
  });
</script>

CDN

If you do not use a build process that supports importing from NPM, you can use SnowMail from a CDN instead.

<div id="snowmail"></div>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/snowmail@latest/dist/main/styles.min.css" />
<script type="module">
  import { render } from 'https://cdn.jsdelivr.net/npm/snowmail@latest/dist/main/index.mjs';
  render({
    element: document.getElementById('snowmail'),
    url: 'https://snowmail.example.com',
    id: '6627b0113f4c7e0d773abc2b',
    providerProps: {}
  });
</script>

Important

It is recommended to replace latest with a specific version number in production.

Server-Only

You can also use SnowMail just to manage forms server-side and write your own client-side code for rendering and styling the form.

import { getForm } from 'snowmail/api.js';
const url = 'https://snowmail.example.com';
const id = '6627b0113f4c7e0d773abc2b';

const inputs = getForm(url, id);
// Write your own code to render the inputs

// Send the response to the server
fetch(`${url}/public-api/forms/${id}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json'
  },
  body: JSON.stringify({
    // If you have two inputs with the names "name" and "email"
    name: 'John Doe',
    email: 'jdoe@example.com'
  })
}).then(async (resp) => {
  if (resp.status === 200) {
    // Email sent
  } else {
    const body = await resp.json();
    // body.title contains the error message
  }
});