Email Test Service

Keine E-Mail ausgewählt.

Nutzung

E-Mail-Empfang

Sende Test-E-Mails an eine beliebige Adresse unter - jede Adresse auf dieser Subdomain wird angenommen und erscheint hier bzw. über die API. Der Button oben generiert eine zufällige, aber lesbare Beispieladresse.

Abruf über die API (für automatisierte Tests)

Basis-URL:
Header: x-api-key:

Der API Key ist kein Geheimnis - er verhindert nur, dass die E-Mails öffentlich ohne jede Einschränkung abrufbar sind. Bitte trotzdem nicht öffentlich posten.

Alle Endpunkte und Parameter: Tab "API-Referenz". Node/TypeScript-Client: Tab "SDK".

Basis-URL:
Auth-Header (alle Endpunkte unten): x-api-key: <key>

GET /api/emails

Listet empfangene Test-E-Mails, gefiltert nach Empfänger/Absender/Zeitraum.

Parameter	Typ	Beschreibung
`recipient`	string	Exakte Empfängeradresse (Abfrage über GSI, empfohlen).
`sender`	string	Exakte Absenderadresse. Zusammen mit `recipient` als Zusatzfilter angewendet.
`from`	ISO-8601	Untere Grenze für `receivedAt` (inklusiv).
`to`	ISO-8601	Obere Grenze für `receivedAt` (inklusiv).
`limit`	number	Max. Anzahl Treffer. Standard 50, Maximum 200.

Ohne recipient/sender wird intern ein Table-Scan verwendet (siehe "Known limitations" im README) - für automatisierte Tests wird mindestens recipient empfohlen.

{
  "items": [
    {
      "id": "<sesMessageId>#<recipient>",
      "sesMessageId": "...",
      "sender": "no-reply@example.com",
      "recipient": "my-test-inbox@<catchall-domain>",
      "receivedAt": "2026-07-13T08:47:07.327Z",
      "subject": "...",
      "rawTruncated": false
    }
  ],
  "count": 1
}

GET /api/emails/{id}

Lädt eine einzelne E-Mail inkl. Inhalt. id muss URL-kodiert werden - sie enthält ein #, das in einer URL sonst als Fragment abgeschnitten und nie zum Server übertragen wird (z. B. %23 statt #).

{
  "id": "...",
  "sesMessageId": "...",
  "sender": "...",
  "recipient": "...",
  "receivedAt": "...",
  "subject": "...",
  "textBody": "...",
  "htmlBody": "...",
  "headers": [{ "name": "...", "value": "..." }],
  "attachmentsMeta": [{ "filename": "...", "contentType": "...", "size": 0 }],
  "rawTruncated": false
}

Fehlerantworten

Status	Bedeutung
400	Fehlende/ungültige Parameter (z. B. leere `id`).
403	Fehlender oder ungültiger `x-api-key`.
404	Keine E-Mail mit dieser `id` gefunden.
500	Unerwarteter Serverfehler.

Für Node/TypeScript gibt es ein kleines SDK, das Suche und Laden von E-Mails kapselt (kein eigenes Auth-Handling, kein Polling - nur die zwei API-Aufrufe der "API-Referenz" als typisierter Client). Quelle: infra/testinfra/emailservice/sdk. Voraussetzung: Node.js 18+ (nutzt das eingebaute globale fetch).

Veröffentlichung

Das Paket @eurobase-pgr-pg/emailservice-sdk wird per GitHub Action (.github/workflows/emailservice-sdk-publish.yml) gebaut und bei jedem Tag emailservice-sdk-v* nach GitHub Packages veröffentlicht - nicht nach npmjs.com, da dieses Repo privat ist. Zum Installieren wird daher ein GitHub-Token benötigt, das Lesezugriff auf Packages dieses (privaten) Repos hat.

1. Zugriff auf GitHub Packages einrichten (einmalig)

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → neues Token mit Scope read:packages erzeugen (der Token-Besitzer braucht mind. Lesezugriff auf dieses Repo, da das Package an ein privates Repo gebunden ist).
Token als Umgebungsvariable verfügbar machen, z.B. in der Shell-Config:

export GH_PACKAGES_TOKEN=<dein-token>

.npmrc anlegen - entweder global (~/.npmrc) oder projektlokal (dann in .gitignore, falls der Token dort landet):

@eurobase-pgr-pg:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GH_PACKAGES_TOKEN}

In einer GitHub-Actions-Workflow eines anderen Repos in dieser Organisation reicht meist secrets.GITHUB_TOKEN statt eines eigenen PAT - siehe emailservice-sdk/README.md für das genaue Setup mit actions/setup-node.

2. Installation

npm install @eurobase-pgr-pg/emailservice-sdk

3. Verwendung

Weitere Filter für listEmails:

// nach Absender, mit Zeitraum und Limit filtern
const { items, count } = await client.listEmails({
  recipient: "my-test-inbox@<catchall-domain>",
  sender: "no-reply@example.com",
  from: new Date(Date.now() - 5 * 60_000), // Date oder ISO-8601-String
  to: new Date(),
  limit: 20,
});

Fehlerbehandlung (z.B. in einem Test-Wartepolling):

import { EmailServiceApiError } from "@eurobase-pgr-pg/emailservice-sdk";

try {
  const email = await client.getEmail(id);
} catch (error) {
  if (error instanceof EmailServiceApiError && error.status === 404) {
    // E-Mail (noch) nicht vorhanden
  } else {
    throw error;
  }
}

Vollständige Details (Release-Prozess, CI-Konsum) siehe infra/testinfra/emailservice/sdk/README.md im Repo.