bimetricsEntwickler
Versand per E Mail

Per E-Mail senden

Als Markdown ansehen

Benötigte Berechtigung:mail:send(E-Mails senden)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/document-mail/send

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

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

Header-Parameter

Idempotency-Key*string

Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

application/json
  1. body

Mail mit einem ausgestellten Dokument.

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.

body?string

Text ohne Signatur, höchstens 6000 Zeichen.

cc?array<string>|

Empfänger in Kopie.

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.

subject?string

Betreff, höchstens 300 Zeichen.

target?

Das ausgestellte Dokument.

to?array<string>|

Empfänger, mindestens einer; zusammen mit cc höchstens 50 und höchstens so viele, wie die Tagesgrenze noch erlaubt.

Antworten

Erfolg.

application/json
  1. response

Eine gesendete Mail, so wie sie rausging.

attachments?array<>|

Anhänge.

body?string

Text mit Signatur und Pflichtangaben, wie versendet.

bouncedAt?string

Unzustellbar seit.

Formatdate-time
cc?array<string>|

Empfänger in Kopie.

companyId?string

ID der Firma.

Formatuuid
createdAt?string

Anlage in bimetrics.

Formatdate-time
createdByUserCompanyId?string

Mitgliedschaft, die gesendet hat; bei der API die des Schlüsselinhabers.

Formatuuid
customerName?string

Name des Kunden.

deliveredAt?string

Zustellung.

Formatdate-time
documentKind?string

Art des Dokuments wie in MailDocument.kind.

failureCode?string

Grund, wenn die Mail nicht rausging.

html?string

Die Mail als HTML, wie versendet.

id?string

ID der Mail.

Formatuuid
number?string

Nummer des Dokuments.

recipientCount?integer

Empfänger samt Kopie; zählt zur Tagesgrenze.

recipients?array<>|

Zustellstand je Empfänger.

replyTo?string

Antwortadresse.

senderAddress?string

Absenderadresse von bimetrics.

senderName?string

Absendername.

sentAt?string

Übergabe an den Maildienst.

Formatdate-time
status?string

queued, sent, delivered, bounced, complained oder failed.

subject?string

Betreff.

targetId?string

ID des Entwurfs bzw. der Mahnung.

Formatuuid
targetKind?string

draft oder reminder.

to?array<string>|

Empfänger.

updatedAt?string

Letzte Änderung.

Formatdate-time
Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document-mail/send" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "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.\n\nViele Grüße\nMuster Studio",  "cc": [],  "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",  "createdAt": "2026-11-04T09:30:00Z",  "createdByUserCompanyId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",  "customerName": "Beispiel GmbH",  "documentKind": "invoice",  "id": "3e0c7a52-1f4b-4c8d-9e2a-6b7c8d9e0f1a",  "number": "RE-2026-0042",  "recipientCount": 1,  "recipients": [    {      "address": "einkauf@beispiel.de",      "channel": "to",      "status": "queued"    }  ],  "replyTo": "buchhaltung@muster-studio.de",  "senderAddress": "versand@rechnungen.bimetrics.de",  "senderName": "Muster Studio",  "status": "queued",  "subject": "Rechnung RE-2026-0042",  "targetId": "821c3664-640a-4e10-b120-a4ff713532f8",  "targetKind": "draft",  "to": [    "einkauf@beispiel.de"  ],  "updatedAt": "2026-11-04T09:30:00Z"}

Mail vorbereiten POST

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`.

Dauerbuchung anlegen POST

Legt eine Dauerbuchung an, wie in der App: Für jede Periode entsteht sofort ein Beleg mit Buchung, auch für vergangene. `POST /api/document/collection/contract/preview` zeigt das vorher. Der Rhythmus ist 1, 3, 6 oder 12 Monate, `end` gilt ausschließlich und liegt nach `start`. Zeilen haben einen festen Betrag. Geprüft wird wie im Formular der App: Bezeichnung, Art `invoice` oder `receipt`, 1 bis 100 Zeilen mit Betrag oder Anteil, Kategorie passend zu Art, Verwendung und Kontenrahmen, Steuersatz 19, 7 oder 0 %, auf Eingangsbelegen auch 9 oder 5,5 %, soweit die Kategorie ihn zulässt, Steuerfall bei 0 % auf Eingangsbelegen und die Gegenpartei der Art, außer alle Kategorien werden direkt gebucht. Verstöße ergeben `400 InvalidBookkeepingChange` mit `context.field`. Bezeichnung, Kategorie und Steuersatz werden nur geprüft, wenn sie neu sind. Eine Wiederholung mit gleichem Idempotency-Key wirkt nicht doppelt. Benötigt einen Schlüssel mit der Berechtigung `collections:write`.