E-Mail-Anmeldungen mit der Notion API sammeln

Viele Leute richten heutzutage ihre eigenen Newsletter ein. Es gibt die aktuellen großen Namen wie Substack und MailChimp, Unternehmen wie Twitter steigen mit Revue ein, und sogar Facebook steigt in das Newsletter-Geschäft ein. Einige Leute versuchen, es näher an die Heimat zu bringen mit einer selbstverwalteten WordPress-Lösung über MailPoet.

Sprechen wir über eine weitere Möglichkeit: Eigene E-Mail-Abonnenten auf die altmodische Art sammeln: ein <form>, das an eine API gesendet wird und die Daten in einem Datenspeicher ablegt.

Die erste Hürde bei der Einrichtung eines Newsletters ist ein Mechanismus zum Sammeln von E-Mails. Die meisten Apps, die Ihnen beim Erstellen und Versenden von Newslettern helfen, bieten Beispiele für Formulare zum Kopieren und Einfügen an. Die meisten dieser Optionen sind jedoch kostenpflichtig, und wir suchen etwas Kostenloses, das vollständig von uns gehostet wird.

Nichts ist praktischer, als unser eigenes System einzurichten, das wir kontrollieren können. In diesem Tutorial richten wir unser eigenes System zum Sammeln von E-Mails für unsere Newsletter basierend auf der Jamstack-Architektur ein. Wir implementieren ein HTML-Formular zum Sammeln von E-Mails für unseren Newsletter, verarbeiten diese E-Mails mit Netlify Functions und speichern sie in einer Notion-Datenbank mit der Notion API.

Aber bevor wir beginnen…

Wir brauchen Folgendes:

• Ein Netlify-Konto
• Ein Notion-Konto
• Ein Mailgun-Konto. Wenn Sie noch keines haben, klicken Sie hier, um ein kostenloses Konto zu erstellen.

Alle diese Dienste sind kostenlos (mit Einschränkungen). Und was Mailgun betrifft, so könnten wir wirklich jeden E-Mail-Dienstanbieter verwenden, der eine API anbietet.

Den gesamten Code, der in diesem Tutorial verwendet wird, finden Sie auf GitHub.

Zuerst Notion

Was ist Notion, fragen Sie? Lassen Sie sie es selbst beschreiben.

Notion ist ein einziger Ort, an dem Sie denken, schreiben und planen können. Erfassen Sie Gedanken, verwalten Sie Projekte oder führen Sie sogar ein ganzes Unternehmen – und tun Sie dies genau so, wie Sie es wünschen.

Mit anderen Worten, Notion ist so etwas wie eine Datenbank, aber mit einer schönen visuellen Oberfläche. Und jede Zeile in der Datenbank erhält ihre eigene „Seite“, auf der das Schreiben von Inhalten dem Schreiben eines Blogbeitrags im WordPress-Block-Editor nicht unähnlich ist.

Und diese Datenbanken können auf vielfältige Weise visualisiert werden, von einer einfachen Tabellenkalkulation über ein Trello-ähnliches Board, eine Galerie, einen Kalender, eine Zeitleiste oder eine... Sie verstehen schon.

Wir verwenden Notion, weil wir Tabellen einrichten können, die unsere Formularantworten speichern, wodurch es im Grunde zu einem Datenspeicher wird. Notion hat auch gerade erst kürzlich eine vollständige API für die öffentliche Nutzung veröffentlicht. Wir können diese API nutzen und mit ihr interagieren über…

Netlify Functions

Netlify Functions sind serverlose API-Endpunkte, die natürlich von Netlifys Hosting-Plattform bereitgestellt werden. Wir können sie in JavaScript oder Go schreiben.

Wir könnten Netlify Forms verwenden, um Formularübermittlungen zu sammeln. Tatsächlich hat Matthew Ström bereits gezeigt, wie das funktioniert. Aber im kostenlosen Plan können wir nur 100 Übermittlungen pro Monat erhalten. Deshalb verwenden wir Netlify Functions – sie können 125.000 Mal pro Monat aufgerufen werden, was bedeutet, dass wir eine Viertelmillion E-Mails pro Monat sammeln können, ohne einen einzigen Cent zu bezahlen.

Lassen Sie uns die Notion-Datenbank einrichten

Das erste, was wir tun müssen, ist, eine Datenbank in Notion zu erstellen. Dazu genügt es, eine neue Seite zu erstellen und dann einen Block für eine vollständige Seite einer Tabelle einzufügen, indem Sie /table eingeben.

Nennen wir unsere Datenbank: Newsletter Emails.

Wir wollen die Dinge ziemlich einfach halten, also sammeln wir nur eine E-Mail-Adresse, wenn sich jemand über das Formular anmeldet. Wir brauchen also wirklich nur eine Spalte in der Tabelle namens E-Mail.

Aber Notion ist etwas intelligenter als das und enthält erweiterte Eigenschaften, die zusätzliche Informationen liefern. Eine davon ist die Eigenschaft „Erstellt am“, die, ihrem Namen getreu, einen Zeitstempel für die Erstellung einer neuen Einreichung ausgibt.

Wir brauchen auch einen Notion API-Token

Um mit unserer Notion-Datenbank interagieren zu können, müssen wir eine Notion-Integration erstellen und einen API-Token erhalten. Neue Integrationen werden nicht in Ihrem Notion-Konto, sondern auf der Notion-Website erstellt, wenn Sie in Ihrem Konto angemeldet sind. Wir geben dieser Integration einen ebenso kreativen Namen wie der Notion-Tabelle: Newsletter Signups.

Sobald die Integration erstellt ist, können wir den Internen Integrations-Token (API-Token) abrufen. Behalten Sie ihn, denn wir werden ihn gleich verwenden.

Standardmäßig können Notion-Integrationen tatsächlich nicht auf Notion-Seiten oder -Datenbanken zugreifen. Wir müssen die spezifische Seite oder Datenbank explizit mit unserer Integration teilen, damit die Integration Informationen in der Tabelle richtig lesen und verwenden kann. Klicken Sie auf den Link Teilen in der oberen rechten Ecke der Notion-Datenbank, verwenden Sie das Dropdown-Menü, um die Integration anhand ihres Namens zu finden, und klicken Sie dann auf Einladen.

Als Nächstes Netlify

Unsere Datenbank ist bereit, Formularübermittlungen über die Notion-API zu empfangen. Jetzt ist es an der Zeit, ein Formular und eine serverlose Funktion zur Verarbeitung der Formularübermittlungen zu erstellen.

Da wir unsere Website auf Netlify einrichten, installieren wir die Netlify CLI auf unserem lokalen Rechner. Öffnen Sie Terminal und verwenden Sie diesen Befehl:

npm install netlify-cli -g

Je nach Ihren Vorlieben können wir uns auf verschiedene Weise bei Netlify authentifizieren. Sie können die erstaunliche Anleitung von Netlify als Ausgangspunkt verwenden. Sobald wir uns bei Netlify authentifiziert haben, müssen wir als Nächstes ein Netlify-Projekt erstellen. Hier sind die Befehle dazu:

$ mkdir newsletter-subscription-notion-netlify-function
$ cd newsletter-subscription-notion-netlify-function
$ npm init

Folgen Sie diesem Commit im GitHub-Projekt: diesem Commit im GitHub-Projekt.

Schreiben wir eine Netlify Function

Bevor wir mit dem Schreiben unserer Netlify Function beginnen, müssen wir zwei Dinge tun.

Erstens müssen wir das npm-Paket [@notionhq/client](https://github.com/makenotion/notion-sdk-js) installieren, ein offizielles Notion JavaScript SDK für die Verwendung der Notion API.

$ npm install @notionhq/client --save

Zweitens müssen wir eine .env-Datei im Stammverzeichnis des Projekts erstellen und die folgenden beiden Umgebungsvariablen hinzufügen:

NOTION_API_TOKEN=<your Notion API token>
NOTION_DATABASE_ID=<your Notion database>

Die Datenbank-ID finden Sie in ihrer URL. Eine typische Notion-Seite hat eine URL wie https://www.notion.so/{workspace_name}/{database_id}?v={view_id}, wobei {database_id} der ID entspricht.

Wir schreiben unsere Netlify Functions im Verzeichnis functions. Daher müssen wir eine netlify.toml-Datei im Stammverzeichnis des Projekts erstellen, um Netlify mitzuteilen, dass unsere Funktionen aus diesem Verzeichnis kompiliert werden müssen.

[build]
functions = "functions"

Erstellen wir nun ein functions-Verzeichnis im Stammverzeichnis des Projekts. Im Verzeichnis functions müssen wir eine Datei index.js erstellen und den folgenden Code hinzufügen. Diese Funktion ist als API-Endpunkt unter /.netlify/functions/index verfügbar.

const { Client, LogLevel } = require('@notionhq/client');

const { NOTION_API_TOKEN, NOTION_DATABASE_ID } = process.env;

async function addEmail(email) {
  // Initialize Notion client
  const notion = new Client({
    auth: NOTION_API_TOKEN,
    logLevel: LogLevel.DEBUG,
  });

  await notion.pages.create({
    parent: {
      database_id: NOTION_DATABASE_ID,
    },
    properties: {
      Email: {
        title: [
          {
            text: {
              content: email,
            },
          },
        ],
      },
    },
  });
}

function validateEmail(email) {
  const re =
    /^(([^<>()[\\]\\\\.,;:\\s@"]+(\\.[^<>()[\\]\\\\.,;:\\s@"]+)*)|(".+"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\])|(([a-zA-Z\\-0-9]+\\.)+[a-zA-Z]{2,}))$/;
  return re.test(String(email).toLowerCase());
}

module.exports.handler = async function (event, context) {
  // Check the request method
  if (event.httpMethod != 'POST') {
    return { statusCode: 405, body: 'Method not allowed' };
  }

  // Get the body
  try {
    var body = JSON.parse(event.body);
  } catch (err) {
    return {
      statusCode: 400,
      body: err.toString(),
    };
    return;
  }

  // Validate the email
  const { email } = body;
  if (!validateEmail(email)) {
    return { statusCode: 400, body: 'Email is not valid' };
  }

  // Store email in Notion
  await addEmail(email);
  return { statusCode: 200, body: 'ok' };
};

Lassen Sie uns das Block für Block aufschlüsseln.

Die Funktion addEmail wird verwendet, um die E-Mail unserer Notion-Datenbank hinzuzufügen. Sie nimmt einen Parameter email, der eine Zeichenkette ist.

Wir erstellen einen neuen Client zur Authentifizierung bei der Notion API, indem wir unser NOTION_API_TOKEN angeben. Wir haben auch den Protokollierungsstufen-Parameter gesetzt, um Informationen über die Ausführung von Befehlen zu erhalten, während wir unser Projekt entwickeln. Diesen können wir entfernen, sobald wir bereit sind, das Projekt in die Produktion zu überführen.

In einer Notion-Datenbank wird jeder Eintrag als Seite bezeichnet. Wir verwenden also die Methode notion.pages.create, um einen neuen Eintrag in unserer Notion-Datenbank zu erstellen. Die Funktion module.exports.handler wird von Netlify Functions verwendet, um die an sie gerichteten Anfragen zu bearbeiten.

Als Erstes prüfen wir die Anfragemethode. Wenn die Anfragemethode etwas anderes als POST ist, senden wir eine Antwort mit dem Statuscode 405 - Method not allowed.

Dann parsen wir das von Frontend gesendete Payload-Objekt (event.body). Wenn wir das Payload-Objekt nicht parsen können, senden wir eine Antwort mit dem Statuscode 400 - Bad request.

Sobald wir die Anfragesnutzlast geparst haben, prüfen wir auf das Vorhandensein einer E-Mail-Adresse. Wir verwenden die Funktion validateEmail, um die Gültigkeit der E-Mail zu prüfen. Wenn die E-Mail ungültig ist, senden wir eine Antwort mit dem Statuscode 400 - Bad request mit einer benutzerdefinierten Nachricht, dass die Email is not valid.

Nachdem wir alle Prüfungen abgeschlossen haben, rufen wir die Funktion addEmail auf, um die E-Mail in unserer Notion-Datenbank zu speichern, und senden eine Erfolgsantwort mit dem Statuscode 200 - Success zurück.

Folgen Sie dem Code im GitHub-Projekt mit Commit ed607db.

Jetzt zu einem grundlegenden HTML-Formular

Unser serverloses Backend ist bereit und der letzte Schritt ist die Erstellung eines Formulars zum Sammeln von E-Mail-Anmeldungen für unseren Newsletter.

Lassen Sie uns eine Datei index.html im Stammverzeichnis des Projekts erstellen und den folgenden HTML-Code hinzufügen. Beachten Sie, dass Markup und Klassen von Bootstrap 5 stammen.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Notion + Netlify Functions Newsletter</title>
  <link href="<https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css>" rel="stylesheet" crossorigin="anonymous">
</head>

<body>
  <div class="container py-5">
    <p>
      Get daily tips related to Jamstack in your inbox.
    </p>

    <div id="form" class="row">
      <div class="col-sm-8">
        <input name="email" type="email" class="form-control" placeholder="Your email" autocomplete="off">
        <div id="feedback-box" class="invalid-feedback">
            Please enter a valid email
        </div>
      </div>
      <div class="col-sm-4">
        <button class="btn btn-primary w-100" type="button" onclick="registerUser()">Submit form</button>
      </div>
    </div>

    <div id="success-box" class="alert alert-success d-none">
      Thanks for subscribing to our newsletter.
    </div>
    <div id="error-box" class="alert alert-danger d-none">
      There was some problem adding your email.
    </div>
  </div>
</body>
<script>
</script>
</html>

Wir haben ein Eingabefeld zum Sammeln von Benutzer-E-Mails. Wir haben eine Schaltfläche, die beim Klicken die Funktion registerUser aufruft. Wir haben zwei Benachrichtigungen, die angezeigt werden: eine für eine erfolgreiche Übermittlung und eine für eine erfolglose Übermittlung.

Da wir die Netlify CLI installiert haben, können wir den Befehl netlify dev verwenden, um unsere Website auf dem lokalen Host-Server auszuführen.

$ netlify dev

Als Nächstes müssen wir etwas JavaScript schreiben, das die E-Mail validiert und eine HTTP-Anfrage an die Netlify Function sendet. Fügen wir den folgenden Code in den <script>-Tag in der Datei index.html ein:

function validateEmail(email) {
  const re =
    /^(([^<>()[\\]\\\\.,;:\\s@"]+(\\.[^<>()[\\]\\\\.,;:\\s@"]+)*)|(".+"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\])|(([a-zA-Z\\-0-9]+\\.)+[a-zA-Z]{2,}))$/;
  return re.test(String(email).toLowerCase());
}

async function registerUser() {
  const form = document.getElementById('form');
  const successBox = document.getElementById('success-box');
  const errorBox = document.getElementById('error-box');
  const feedbackBox = document.getElementById('feedback-box');
  const email = document.getElementsByName('email')[0].value;

  if (!validateEmail(email)) {
    feedbackBox.classList.add('d-block');
    return;
  }

  const headers = new Headers();
headers.append('Content-Type', 'application/json');
  
  const options = {
    method: 'POST',
    headers,
    body: JSON.stringify({email}),
  };

  const response = await fetch('/.netlify/functions/index', options);

  if (response.ok) {
    form.classList.add('d-none');
    successBox.classList.remove('d-none');
  }
  else {
    form.classList.add('d-none');
    errorBox.classList.remove('d-none');
  }
}

In der Funktion registerUser prüfen wir die Gültigkeit der E-Mail-Eingabe mit einer RegEx-Funktion (validateEmail). Wenn die E-Mail ungültig ist, fordern wir den Benutzer auf, es erneut zu versuchen. Nachdem wir die E-Mail validiert haben, rufen wir die fetch-Methode auf, um eine POST-Anfrage an unsere Netlify Function unter /.netlify/functions/index mit einem Payload-Objekt, das die E-Mail des Benutzers enthält, zu senden.

Basierend auf der Antwort zeigen wir dem Benutzer eine Erfolgsmeldung an, andernfalls eine Fehlermeldung.

Folgen Sie dem Code im GitHub-Projekt mit Commit cd9791b.

Abrufen der Mailgun-Anmeldedaten

E-Mails in unserer Datenbank zu haben ist gut, aber nicht genug, weil wir nicht wissen, wie wir sie verwenden werden. Der letzte Schritt ist also, einem Abonnenten nach der Anmeldung eine Bestätigungs-E-Mail zu senden.

Wir werden nicht sofort nach der Anmeldung eines Benutzers eine Nachricht senden. Stattdessen richten wir eine Methode ein, um die E-Mail-Anmeldungen der letzten 30 Minuten abzurufen und dann die E-Mail zu senden. Eine Verzögerung bei der automatisch generierten E-Mail lässt die Willkommensnachricht etwas persönlicher wirken, finde ich.

Wir verwenden Mailgun zum Senden, aber auch hier könnten wir wirklich jeden E-Mail-Dienstanbieter mit einer API verwenden. Gehen wir zum Mailgun-Dashboard und navigieren Sie in der Seitenleiste zu den Einstellungen → API-Schlüssel.

Kopieren wir den privaten API-Schlüssel und fügen ihn in die .env-Datei wie folgt ein:

MAILGUN_API_KEY=<your Mailgun api key>

Jede E-Mail muss von einer Absenderadresse stammen. Daher benötigen wir noch die Mailgun-Domäne, von der die E-Mails gesendet werden. Um unsere Mailgun-Domäne zu erhalten, müssen wir zum Bildschirm Senden → Domänen gehen.

Kopieren wir unsere Mailgun-Sandbox-Domäne und fügen sie wie folgt in die .env-Datei ein:

MAILGUN_DOMAIN=<your Mailgun domain>

Senden einer Bestätigungs-E-Mail

Bevor wir mit dem Schreiben unserer Netlify Function zum Senden einer E-Mail-Bestätigung beginnen, müssen wir das npm-Paket [mailgun-js](https://github.com/mailgun/mailgun-js) installieren, das ein offizielles Mailgun JavaScript SDK für die Verwendung der Mailgun API ist.

$ npm install mailgun-js --save

Wir verwenden den Endpunkt /.netlify/functions/index zum Senden von Willkommens-E-Mails. Erstellen wir also im Verzeichnis functions eine neue Datei welcome.js und fügen den folgenden Code hinzu:

const { Client, LogLevel } = require('@notionhq/client');
const mailgun = require('mailgun-js');

const {
  NOTION_API_TOKEN,
  NOTION_DATABASE_ID,
  MAILGUN_API_KEY,
  MAILGUN_DOMAIN,
} = process.env;

async function fetchNewSignups() {
  // Initialize notion client
  const notion = new Client({
    auth: NOTION_API_TOKEN,
    logLevel: LogLevel.DEBUG,
  });

  // Create a datetime that is 30 mins earlier than the current time
  let fetchAfterDate = new Date();
  fetchAfterDate.setMinutes(fetchAfterDate.getMinutes() - 30);

  // Query the database
  // and fetch only entries created in the last 30 mins
  const response = await notion.databases.query({
    database_id: NOTION_DATABASE_ID,
    filter: {
      or: [
        {
          property: 'Added On',
          date: {
            after: fetchAfterDate,
          },
        },
      ],
    },
  });

  const emails = response.results.map((entry) => entry.properties.Email.title[0].plain_text);

  return emails;
}

async function sendWelcomeEmail(to) {
  const mg = mailgun({ apiKey: MAILGUN_API_KEY, domain: MAILGUN_DOMAIN });

  const data = {
    from: `Ravgeet Dhillon <postmaster@${MAILGUN_DOMAIN}>`,
    to: to,
    subject: 'Thank you for subscribing',
    text: "Thank you for subscribing to my newsletter. I'll be sending daily tips related to JavScript.",
  };

  await mg.messages().send(data);
}

module.exports.handler = async function (event, context) {
  // Check the request method
  if (event.httpMethod != 'POST') {
    return { statusCode: 405, body: 'Method not allowed' };
  }

  const emails = await fetchNewSignups();

  emails.forEach(async (email) => {
    await sendWelcomeEmail(email);
  });

  return { statusCode: 200, body: 'ok' };
};

Der obige Code enthält zwei Hauptfunktionen, die wir verstehen müssen. Erstens haben wir eine Funktion fetchNewSignups. Wir verwenden den Notion SDK-Client, um die Einträge in unserer Notion-Datenbank abzurufen. Wir haben einen Filter verwendet, um nur die E-Mails abzurufen, die in den letzten 30 Minuten hinzugefügt wurden. Sobald wir eine Antwort von der Notion API erhalten, durchlaufen wir die Antwort und ordnen die E-Mails einem emails-Array zu.

Zweitens haben wir eine Funktion sendWelcomeEmail. Diese Funktion wird verwendet, um über die Mailgun API eine E-Mail an den neuen Abonnenten zu senden.

Um alles zusammenzuführen, durchlaufen wir die neuen E-Mails in der Funktion module.exports.handler und senden eine Willkommens-E-Mail an jede neue E-Mail.

Diese Funktion ist unter localhost:8888/.netlify/functions/welcome verfügbar.

Folgen Sie dem Code im GitHub-Projekt mit Commit b802f93.

Lassen Sie uns das testen!

Nachdem unser Projekt fertig ist, müssen wir zuerst das Formular testen und sehen, ob die E-Mail in unserer Notion-Datenbank gespeichert wird. Gehen wir zu localhost:8888 und geben Sie eine gültige E-Mail-Adresse ein.

Perfekt! Wir haben die Erfolgsmeldung erhalten. Gehen wir nun zu unserer Notion-Datenbank, um zu sehen, ob die E-Mail-Adresse erfasst wurde.

Als Nächstes senden wir eine POST-Anfrage an localhost:8888/.netlify/functions/welcome von Postman und überprüfen unseren Posteingang auf die Bestätigungs-E-Mail des Abonnements.

Sehen Sie die E-Mail nicht in Ihrem Posteingang? Stellen Sie sicher, dass Sie Ihren Spam-Ordner überprüfen.

Was kommt als Nächstes?

Der nächste Schritt von hier aus wäre, ein Skript einzurichten, das alle 30 Minuten ausgeführt wird und den Willkommens-Endpunkt aufruft. Derzeit bietet Netlify keine Möglichkeit, CRON-Jobs auszuführen. Wir können also GitHub Actions dafür einrichten.

Außerdem können wir den Willkommens-Endpunkt mit Sicherheitsmechanismen wie einem einfachen Passwort oder einem JWT-Token sichern. Dies verhindert, dass jemand im Internet den welcome-Endpunkt aufruft und massenhaft Spam an unsere Abonnenten sendet.

Da haben wir es! Wir haben erfolgreich eine Jamstack-Methode zum Sammeln von E-Mails für einen Newsletter implementiert. Der größte Vorteil eines solchen Vorgehens ist, dass wir gleichzeitig viel über verschiedene Technologien lernen können. Wir haben Dienste und APIs miteinander verbunden, die E-Mail-Adressen sammeln, Übermittlungen validieren, Daten in Datenbanken einstellen und sogar E-Mails versenden. Es ist ziemlich cool, dass wir mit relativ wenig so viel erreichen können.

Ich hoffe, Sie haben das Lesen und Lernen aus diesem Artikel genauso genossen wie ich das Schreiben für Sie. Lassen Sie mich in den Kommentaren wissen, wie Sie diese Methode zu Ihrem Vorteil genutzt haben. Viel Spaß beim Codieren!