Node.js.

The official client wraps both halves of the API: sending a submission, and reading forms and submissions back. No runtime dependencies — Node 18 and up brings everything it needs.

Installation

bash

npm install mailan-node

TypeScript types are included, and the package ships as both ESM and CommonJS — „import" and „require" both work.

Sending a submission

No API key needed here: the form's access key is the credential. The second argument holds your own fields, the third the values that steer the notification mail instead of being stored.

JavaScript

import { Mailan } from 'mailan-node'; const mailan = new Mailan(); await mailan.submit( process.env.MAILAN_ACCESS_KEY, { name: 'Erika Mustermann', email: 'erika@beispiel.de', message: 'Hallo!' }, { subject: 'Neue Anfrage', replyTo: 'erika@beispiel.de' }, );

File uploads

With files the client switches to multipart by itself. „fileFromPath" reads from disk; where there is no file system, hand over the bytes directly.

JavaScript

import { Mailan, fileFromPath } from 'mailan-node'; await mailan.submit( ACCESS_KEY, { name: 'Erika' }, { files: [await fileFromPath('./lebenslauf.pdf')] }, ); // Ohne Dateisystem: await mailan.submit(ACCESS_KEY, { name: 'Erika' }, { files: [{ filename: 'notiz.txt', content: 'Inhalt', contentType: 'text/plain' }], });

Forms with a captcha

The client solves the ALTCHA proof of work by itself. By default it only does so after the server rejected the first attempt for a failed captcha — that saves the computation on the majority of forms that need none. „captcha: true" solves up front and saves a round trip.

JavaScript

await mailan.submit(KEY, fields); // 'auto' — Standard await mailan.submit(KEY, fields, { captcha: true }); // vorab lösen await mailan.submit(KEY, fields, { captcha: false }); // nie lösen

Reading forms and submissions

This half does need an API key — create one in the dashboard under „API keys". „iterate" follows the cursor across all pages and stops fetching as soon as you leave the loop.

JavaScript

import { Mailan } from 'mailan-node'; const mailan = new Mailan({ apiKey: process.env.MAILAN_API_KEY }); const forms = await mailan.forms.list(); for await (const submission of mailan.submissions.iterate({ formId: forms[0].id })) { console.log(submission.submitted_at, submission.data); } const page = await mailan.submissions.list({ limit: 50 }); // eine Seite const one = await mailan.submissions.get(page.items[0].id); // eine Einsendung

Errors

Every failure is a typed error, so there is no need to read status codes by hand. Note that submissions are never retried automatically: a request that timed out may still have been stored, and a retry would duplicate it. Reads are retried.

JavaScript

import { MailanRateLimitError, MailanForbiddenError } from 'mailan-node'; try { await mailan.submit(KEY, fields); } catch (error) { if (error instanceof MailanRateLimitError && error.quotaExceeded) { // Monatskontingent erreicht } else if (error instanceof MailanForbiddenError && error.reason === 'origin') { // Absender-Domain nicht freigegeben } else { throw error; } }

Your own instance

Point the client at your own installation — everything else stays identical.

JavaScript

const mailan = new Mailan({ baseUrl: 'https://formulare.example.com', apiKey: process.env.MAILAN_API_KEY, });