bimetricsEntwickler
Versand per E Mail

Mail vorbereiten

Als Markdown ansehen

Benötigte Berechtigung:sales:read(Ausgangsrechnungen und Entwürfe lesen)

POST
/api/document-mail/preview

Liefert, was der Dialog „Per E-Mail senden“ der App vorschlägt: Empfänger aus dem Dokument oder seinem Kontakt, Betreff und Text aus der Vorlage der Firma mit den Werten des Dokuments, Signatur, Anhänge und die letzte Sendung. html zeigt die ganze Mail, wie sie versendet würde. Versendet wird nichts. Bei einem Entwurf antwortet die Route mit 409 DocumentMailNotIssued.

Benötigt einen Schlüssel mit der Berechtigung sales:read oder read.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Request-Body

application/json
  1. body

Dokument und Anhänge einer Mail.

attachments?array<>

Weitere Dateien nach PDF und XML, in dieser Reihenfolge, höchstens 10. Alle Anhänge zusammen, PDF und XML eingerechnet, dürfen höchstens 10 MiB groß sein (400 DocumentMailAttachmentsTooLarge). Zu einer XRechnung gehen keine weiteren Dateien (400 DocumentMailAttachmentsNotAllowed). Eine Datei, die es nicht mehr gibt: 409 DocumentMailAttachmentUnavailable mit ihrer Position in context.index.

includePdf?boolean

Nur bei einer XRechnung: hängt zusätzlich das PDF an. Andere Dokumente haben ihr PDF immer dabei.

includeXml?boolean

Hängt zusätzlich das XML der E-Rechnung an, wo xmlAvailable gilt. Eine XRechnung hat es immer dabei.

target?

Das ausgestellte Dokument.

Antworten

Erfolg.

application/json
  1. response

Vorschlag für die Mail, wie ihn der Dialog der App zeigt.

attachmentLimitBytes?integer

Höchstgröße aller Anhänge zusammen in Byte, PDF und XML eingerechnet.

attachments?array<>|

Anhänge der Mail: PDF und XML des Dokuments, danach die weiteren Dateien.

body?string

Text aus der Vorlage mit den Werten des Dokuments, ohne Signatur.

cc?array<string>|

Immer leer.

contactId?string

Kontakt des Empfängers, falls vorhanden.

Formatuuid
document?

Das Dokument.

html?string

Die ganze Mail als HTML mit Signatur und Pflichtangaben, wie sie versendet würde.

lastDelivery?

Die letzte Mail mit diesem Dokument, auch aus der App oder per MCP.

maxExtraAttachments?integer

Höchstzahl weiterer Dateien.

sender?

Absender und Stand des E-Mail-Versands.

signature?string

Signatur unter dem Text.

subject?string

Betreff aus der Vorlage mit den Werten des Dokuments.

to?array<string>|

Vorgeschlagene Empfänger: die Adresse aus dem Dokument oder seinem Kontakt; leer, wenn keine bekannt ist.

values?|

Werte der Platzhalter dieses Dokuments, nach Namen ohne Klammern, etwa Betrag.

xmlAvailable?boolean

Das XML der E-Rechnung lässt sich mit includeXml anhängen.

xrechnung?boolean

XRechnung: Das XML ist immer dabei, das PDF nur mit includePdf.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document-mail/preview" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "attachmentLimitBytes": 10485760,  "attachments": [    {      "blobId": "5b1e2f0a-7c3d-4e8f-9a1b-2c3d4e5f6a7b",      "contentType": "application/pdf",      "filename": "RE-2026-0042.pdf",      "kind": "pdf",      "length": 48213,      "sha256": "9f2c4e1a7b3d5f6081a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708"    }  ],  "body": "Hallo,\n\nanbei erhältst du die Rechnung RE-2026-0042 über 1.190,00 €, fällig am 16.11.2026.",  "cc": [],  "document": {    "customerName": "Beispiel GmbH",    "kind": "invoice",    "number": "RE-2026-0042",    "target": {      "id": "821c3664-640a-4e10-b120-a4ff713532f8",      "kind": "draft"    }  },  "html": "<!doctype html>…",  "maxExtraAttachments": 10,  "sender": {    "companyDailyLimit": 20,    "mode": "bimetrics",    "replyTo": "buchhaltung@muster-studio.de",    "senderAddress": "versand@rechnungen.bimetrics.de",    "senderName": "Muster Studio",    "sendingEnabled": true,    "sentToday": 2,    "status": "active"  },  "signature": "Viele Grüße\nMuster Studio",  "subject": "Rechnung RE-2026-0042",  "to": [    "einkauf@beispiel.de"  ],  "values": {    "Betrag": "1.190,00 €",    "Dokument": "Rechnung RE-2026-0042",    "Fällig am": "16.11.2026",    "Kunde": "Beispiel GmbH",    "Nummer": "RE-2026-0042"  },  "xmlAvailable": true,  "xrechnung": false}

Datei für eine Mail hochladen POST

Speichert eine Datei, die du danach mit `attachments` an `previewDocumentMail` und `sendDocumentMail` übergibst, als `{"uploadId": …}`. Die Datei wird kein Beleg und taucht nirgends sonst auf; bimetrics löscht sie nicht von selbst. Den Typ erkennt bimetrics am Inhalt: Ein PNG namens `Lageplan.pdf` heißt danach `Lageplan.png`. Andere Typen: `400 DocumentMailAttachmentType`, größer als 10 MiB: `400 DocumentMailAttachmentsTooLarge`. Benötigt einen Schlüssel mit der Berechtigung `mail:send`.

Per E-Mail senden POST

Sendet ein ausgestelltes Dokument an die genannten Empfänger, wie „Per E-Mail senden“ in der App: Absender ist bimetrics, Antworten gehen an die Antwortadresse der Firma, unter dem Text stehen Signatur und Pflichtangaben. Betreff und Text gehen genau so raus, wie du sie schickst. Platzhalter wie `{Betrag}` füllt nur die Vorschau. Unumkehrbar. Je Firma gehen höchstens 20 Empfänger am Tag raus, in der Testphase 3, für App, API und MCP zusammen (`429 DocumentMailLimitExceeded`). Ohne eingerichteten E-Mail-Versand antwortet die Route mit `409 DocumentMailNotConfigured`, in der Testphase vor der Bestätigung der E-Mail-Adresse mit `403 MailNotConfirmed`. Eine Wiederholung mit gleichem Idempotency-Key sendet nichts doppelt. Benötigt einen Schlüssel mit der Berechtigung `mail:send`.