E-Mails versenden

POST /v1/emails reiht eine E-Mail ein. Dafür braucht es einen Key mit sending_access oder full_access.

Felder

Feld	Typ	Regeln
from	Adresse	Pflicht. Eine verifizierte Domain Ihres Kontos.
to	Adresse oder Array	Pflicht, mindestens eine Adresse.
cc, bcc	Adresse oder Array	Optional.
replyTo	Adresse oder Array	Optional, eine Adresse oder mehrere.
subject	String	Pflicht, eine Zeile, höchstens 998 Zeichen.
html, text	String	Mindestens eines davon.
tags	Objekt	Bis zu 10. Namen aus Buchstaben, Ziffern, - und _ (höchstens 64), Werte höchstens 256 Zeichen. Tags kommen mit der E-Mail und in den Webhook-Ereignissen zurück.
headers	Objekt	Bis zu 20 zusätzliche Header, siehe unten.
attachments	Array	Siehe Anhänge und eingebettete Bilder.
scheduledAt	Datum und Zeit	Optional. Später versenden, siehe Geplanter Versand.

to, cc und bcc fassen zusammen höchstens 50 Empfänger, die ganze E-Mail höchstens 15 MB wie versendet: die MIME-Nachricht, die letr.dev erstellt, mit Kodierung, Headern und DKIM-Signatur. Das lässt Platz für etwa 10 MB Anhänge.

Anzeigenamen

Jede Adresse kann einen Anzeigenamen tragen: "Ada Lovelace <[email protected]>". Die einfache Form "[email protected]" geht ebenfalls.

{
  "from": "Acme Billing <[email protected]>",
  "to": ["Ada Lovelace <[email protected]>", "[email protected]"],
  "replyTo": "Acme Support <[email protected]>",
  "subject": "Invoice 1042",
  "html": "<p>Your invoice is attached.</p>",
  "text": "Your invoice is attached.",
  "tags": { "type": "invoice" }
}

Eigene Header

headers ergänzt Felder wie In-Reply-To und References für Konversationen, List-Unsubscribe oder X-Entity-Ref-ID. Namen müssen RFC-5322-Feldnamen sein, Werte höchstens 998 Zeichen ohne Zeilenumbruch, und jeder Name darf einmal vorkommen.

Diese Header setzt letr.dev selbst und lehnt sie mit 422 reserved_header ab: From, Sender, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, Return-Path, MIME-Version, DKIM-Signature, Received, Feedback-ID, jeden Content-*- und jeden X-Letr-*-Header.

Wiederholen ohne Duplikate

Senden Sie einen Idempotency-Key-Header (höchstens 255 Zeichen) und wiederholen Sie nach einem Timeout mit demselben Key. Eine Wiederholung mit gleichem Key und gleichem Inhalt liefert die ID der ersten E-Mail mit ihrem aktuellen Status und versendet nichts Neues. Derselbe Key mit anderem Inhalt ergibt 422 idempotency_key_reused. letr.dev kennt einen Key mindestens 32 Tage lang und gibt ihn spätestens einen Tag danach frei; dann versendet derselbe Key eine neue E-Mail.

curl https://api.letr.dev/v1/emails \
  -H "Authorization: Bearer $LETR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-1042" \
  -d @email.json

Testempfänger

An diese Adressen versenden Sie, um letr.dev auszuprobieren, ohne ein echtes Postfach zu erreichen:

• [email protected]: versendet, dann zugestellt.
• [email protected]: versendet, dann abgewiesen (hart, 550 5.1.1); sperrt nichts.
• [email protected]: versendet, zugestellt, dann als Spam gemeldet; sperrt nichts.
• [email protected]: abgelehnt, als stünde die Adresse auf der Sperrliste (422 recipient_suppressed).

Nach einem Pluszeichen darf ein Label folgen, zum Beispiel [email protected], damit Sie Ihre Tests unterscheiden.

Sind alle Empfänger Testadressen, verlässt die E-Mail letr.dev nie. Sie darf jede Absenderadresse an einer Domain Ihres Kontos oder an test.letr.dev verwenden und zählt weder zum Verbrauch noch zur Monatsobergrenze, zur Tageslimite oder zu den Bounce- und Beschwerderaten. Ihre Ereignisse und Webhooks sind echt. Mischt eine E-Mail Test- und echte Empfänger, gelten für die ganze E-Mail die normalen Regeln. Jede andere Adresse an test.letr.dev wird mit 422 invalid_recipients abgelehnt.

Geplanter Versand

Mit scheduledAt versenden Sie später: mindestens 1 Minute und höchstens 7 Tage in der Zukunft, sonst lautet die Antwort 422 invalid_scheduled_at. Die E-Mail entsteht mit dem Status scheduled und zählt zum Verbrauch, wenn sie versendet wird. Ist das Konto pausiert oder deaktiviert, wenn sie fällig wird, schlägt sie fehl, ohne versendet zu werden, und zählt nicht. Eine E-Mail nur an Testempfänger lässt sich nicht planen.

{
  "from": "Acme <[email protected]>",
  "to": "[email protected]",
  "subject": "Your trial ends tomorrow",
  "text": "Your trial ends tomorrow.",
  "scheduledAt": "2026-11-03T08:00:00Z"
}

Bis sie versendet ist, stornieren Sie sie mit POST /v1/emails/{id}/cancel, mit einem Key mit full_access oder dem Versand-Key, der sie erstellt hat. Die Antwort ist die E-Mail mit dem Status canceled. Wartet sie nicht mehr, ergibt das Stornieren 409 not_scheduled.

curl -X POST https://api.letr.dev/v1/emails/$ID/cancel \
  -H "Authorization: Bearer $LETR_API_KEY"

E-Mails lesen

GET /v1/emails/{id} liefert eine E-Mail mit Status und Ereignissen. GET /v1/emails listet die E-Mails des Kontos, neueste zuerst, innerhalb des Nachrichtenverlaufs: status filtert nach einem oder mehreren Status (scheduled, canceled, queued, sent, delivered, deferred, bounced, complained, failed, durch Komma getrennt), q findet die E-Mail-ID oder einen Teil eines Empfängers oder des Betreffs (3 bis 200 Zeichen), limit ist 1 bis 100 (Standard 50), und nextCursor aus der Antwort kommt als cursor in die nächste Anfrage. Die Liste braucht einen Key mit read_only oder full_access.

GET /v1/emails/{id}/content liefert, was letr.dev versendet hat: die Header, text, html und die Liste der Anhänge; GET /v1/emails/{id}/content/attachments/{index} liefert die Bytes eines Anhangs, index ist seine Position in dieser Liste. Der Inhalt bleibt verschlüsselt gespeichert, solange die E-Mail im Verlauf ist, ausser eine Löschung des Empfängers entfernt ihn früher. Ein Key mit sending_access liest nur einzelne E-Mails, die er versendet hat (die E-Mail, ihren Inhalt und ihre Anhänge), und kann nicht auflisten; read_only und full_access lesen jede E-Mail des Kontos.

curl "https://api.letr.dev/v1/emails?status=bounced,failed&limit=20" \
  -H "Authorization: Bearer $LETR_API_KEY"

Antworten

Status	Wann
202	Gespeichert und eingereiht; die Antwort enthält id und status.
400	Der Inhalt ist kein lesbares JSON, oder der Idempotency-Key ist länger als 255 Zeichen.
401	Kein Key oder ein unbekannter, widerrufener oder abgelaufener Key.
403	Konto nicht aktiv oder pausiert, Key ohne Berechtigung oder eine Absenderdomain, die der Key nicht verwenden darf.
422	Ein Feld verletzt eine Regel oben, die Domain ist nicht verifiziert oder ein Empfänger ist gesperrt.
429	Ihre Monatsobergrenze oder die Tageslimite ist erreicht, oder zu viele Anfragen.

Unter Fehler stehen alle Codes.