Node.js.

Der offizielle Client kapselt beide Hälften der API: eine Einsendung verschicken und Formulare wie Einsendungen wieder auslesen. Ohne Laufzeit-Abhängigkeiten — ab Node 18 ist alles Nötige an Bord.

Installation

bash

npm install mailan-node

TypeScript-Typen sind enthalten, und das Paket wird als ESM und als CommonJS ausgeliefert — „import" und „require" funktionieren beide.

Eine Einsendung verschicken

Hier braucht es keinen API-Key: Der Access-Key des Formulars ist die Berechtigung. Das zweite Argument enthält deine eigenen Felder, das dritte die Werte, die die Benachrichtigungsmail steuern, statt gespeichert zu werden.

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' }, );

Datei-Uploads

Sobald Dateien dabei sind, wechselt der Client selbst auf multipart. „fileFromPath" liest von der Platte; wo es kein Dateisystem gibt, übergibst du die Bytes direkt.

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' }], });

Formulare mit Captcha

Der Client löst den ALTCHA-Proof-of-Work selbst. Standardmäßig erst, nachdem der Server den ersten Versuch wegen Captcha abgelehnt hat — das spart die Rechenzeit bei der Mehrheit der Formulare, die keines brauchen. „captcha: true" löst vorab und spart einen Umlauf.

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

Formulare und Einsendungen auslesen

Diese Hälfte braucht einen API-Key — anzulegen im Dashboard unter „API-Keys". „iterate" folgt dem Cursor über alle Seiten und hört auf zu laden, sobald du die Schleife verlässt.

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

Fehler

Jeder Fehlschlag ist ein typisierter Fehler; Status-Codes musst du nicht selbst auswerten. Wichtig: Einsendungen werden nie automatisch wiederholt — eine abgelaufene Anfrage kann trotzdem gespeichert worden sein, ein Retry würde sie verdoppeln. Lesende Aufrufe werden wiederholt.

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; } }

Die eigene Instanz

Zeig dem Client deine eigene Installation — alles Übrige bleibt gleich.

JavaScript

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