@mailto.foo/sdk

The JavaScript SDK for mailto.foo — a headless email subscription and contact form service. Drop it in via script tag or npm, hand it your publish key, and it handles bot protection and delivers only verified submissions to your dashboard.

No backend code required on your end.

Installation

npm install @mailto.foo/sdk

Or via CDN (no npm needed):

<script src="https://cdn.jsdelivr.net/npm/@mailto.foo/sdk/dist/sdk.min.js"></script>

Usage

npm / ESM

import { Mailto } from '@mailto.foo/sdk'

const mailto = new Mailto({ publishKey: 'pk_your_publish_key' })

await mailto.subscribe({ email: '[email protected]' })

Script tag

The CDN build auto-enhances any <form> whose action points at your subscribe endpoint — no JavaScript required:

<script src="https://cdn.jsdelivr.net/npm/@mailto.foo/sdk/dist/sdk.min.js"></script>

<form action="https://api.mailto.foo/your_publish_key/subscribe">
  <input type="email" name="email" required>
  <button type="submit">Subscribe</button>
</form>

On submit, the SDK intercepts the form, calls subscribe with the form fields, resets the form on success, and dispatches mailto:submitting / mailto:success / mailto:error custom events on the form element so you can hook in your own UI:

form.addEventListener('mailto:submitting', () => showLoading())
form.addEventListener('mailto:success', () => showThankYou())
form.addEventListener('mailto:error', (e) => showError(e.detail.error.message))

By default the SDK only fires events and resets the form — it does not touch any elements on the page. Add data-verbose to the form to opt into automatic UI management:

• It injects a .mailto-foo-error and a .mailto-foo-success element into the form (if not already present) and fills them with the error or success message on submit.
• Any element matching .mailto-foo-button, button[type="submit"], or input[type="submit"] is disabled (and gets data-loading="true") while the request is in flight, so you can style a loading state.

<form action="https://api.mailto.foo/your_publish_key/subscribe" data-verbose>
  <input type="email" name="email" required>
  <div class="mailto-foo-error"></div>
  <div class="mailto-foo-success"></div>
  <button type="submit" class="mailto-foo-button">Subscribe</button>
</form>

The SDK is also exposed as window.Mailto for manual usage:

const mailto = new Mailto({ publishKey: 'pk_your_publish_key' })

await mailto.subscribe({ email: '[email protected]' })

Error handling

subscribe throws an Error with the message from the API on failure, so you can catch it directly:

try {
  await mailto.subscribe({ email: '[email protected]' })
} catch (err) {
  console.error(err.message) // e.g. "Email already subscribed"
}

Publish Key

Your publish key (pk_xxx) is tied to your mailto.foo account and the domain you registered. It is safe to expose in frontend code — it only allows submissions, not reads. Get your publish key from your mailto.foo dashboard.

License

MIT