form-to-inbox

form-to-inbox is a lightweight Convex forms backend for contact forms, quote requests, and lead capture workflows. It stores typed form submissions in Convex and can send instant email notifications with Inbound.

• GitHub: https://github.com/Noisemaker111/form-to-inbox
• npm package metadata: https://registry.npmjs.org/form-to-inbox

Why use form-to-inbox?

• Drop-in Convex form handling with a single formSubmissions table.
• Built for common website forms: contact, sales, quote, and support requests.
• Optional email notifications on submit using INBOUND_API_KEY.
• Supports default to / from values with per-submission overrides.
• Works with arbitrary extra fields via customFields: { key, value }[].

Install

npm install form-to-inbox

Quick start

1) Add schema in convex/schema.ts

Convex schema files have special restrictions, so copy this table into your schema file.

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  formSubmissions: defineTable({
    formType: v.string(),

    name: v.optional(v.string()),
    email: v.optional(v.string()),
    phone: v.optional(v.string()),

    address: v.optional(v.string()),
    city: v.optional(v.string()),

    subject: v.optional(v.string()),
    message: v.optional(v.string()),

    customFields: v.optional(
      v.array(v.object({ key: v.string(), value: v.string() }))
    ),

    to: v.string(),
    from: v.string(),
    status: v.string(),
    createdAt: v.number(),
    notes: v.optional(v.string()),
  })
    .index("by_formType", ["formType"])
    .index("by_status", ["status"])
    .index("by_createdAt", ["createdAt"]),
});

2) Add Convex functions in convex/forms.ts

import { convexForms } from "form-to-inbox/server";

export const {
  submitForm,
  getAllSubmissions,
  getSubmissionsByType,
  getNewSubmissions,
  updateStatus,
  sendNotification,
} = convexForms({
  defaultTo: "[email protected]",
  defaultFrom: "[email protected]",
  sendEmailOnSubmit: true,
});

3) Submit from your frontend

import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

const submitForm = useMutation(api.forms.submitForm);

await submitForm({
  formType: "Contact",
  name: "Jane Doe",
  email: "[email protected]",
  message: "Hello!",
  customFields: [{ key: "Source", value: "Landing Page" }],
});

Email notifications with Inbound

Set your API key in the Convex dashboard:

INBOUND_API_KEY=your_inbound_key

If sendEmailOnSubmit: true and INBOUND_API_KEY is set, submitForm sends a notification email after writing the submission.

API overview

convexForms() returns:

• submitForm: insert a new submission and optionally trigger email.
• getAllSubmissions: list all submissions.
• getSubmissionsByType: filter submissions by formType.
• getNewSubmissions: list submissions with a new status.
• updateStatus: update submission workflow status.
• sendNotification: send email for an existing submission.

Notes

• Convex schemas cannot reliably import table definitions from npm packages, so schema setup is copy/paste.
• For strict side-effect boundaries, set sendEmailOnSubmit: false and call sendNotification from an action or scheduler.

Resources

• Convex docs: https://docs.convex.dev
• Inbound package metadata: https://registry.npmjs.org/inboundemail

License

MIT