API, joukkokirjeet ja sähköpostilähetys

Lähetä kirjeitä suoraan ohjelmistostasi – REST API:n kautta, joukkokirjeenä tai yksinkertaisesti sähköpostitse. Claude-liitin käyttää samoja toimintoja.

Todennus

Luo avain kohdassa Tili → API-avaimet ja lähetä se bearer-tunnuksena. Jokainen pyyntö veloittaa vain kyseisen tilin saldoa.

curl -H "Authorization: Bearer mbx_…" https://mcpbrief.de/api/v1/balance

OpenAPI-kuvaus: https://mcpbrief.de/openapi.json

Päätepisteet

GET	/balance	Saldo, hinnat, lähettäjä, päiväraja
POST	/letter/price	Tarkista osoite, muodosta kirje, sivut ja hinta + PDF-esikatselu (ei lähetä mitään)
POST	/letter/send	Lähetä kirje (teksti, PDF, DOCX, kuva; liitteet, duplex, kustannuspaikka)
GET	/letter/{id}	Tila ja seurantanumero
POST	/letter/{id}/cancel	Peru ennen tulostusta (hyvitys)
POST	/letter/{id}/resend	Lähetä uudelleen
GET	/letters?limit=&status=&since=&cost_center=&batch_id=	Luettelo kirjeistäsi, suodatettavissa
POST	/letters/batch/price	Tarkista joukkokirje: kaikki osoitteet, paikkamerkit, kokonaishinta
POST	/letters/batch/send	Lähetä joukkokirje (enint. 200 vastaanottajaa)

Esimerkki: kirjattu kirje liitteellä

curl -X POST https://mcpbrief.de/api/v1/letter/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipient": {"name": "Muster GmbH", "street": "Ringstraße 5",
                "zip": "1010", "city": "Wien", "country": "AT"},
  "subject": "Rechnung 2026-17",
  "content": "Sehr geehrte Damen und Herren,\n\nanbei …",
  "attachments": [{"file_base64": "JVBERi0…", "file_name": "rechnung.pdf"}],
  "delivery": "registered", "duplex": true, "cost_center": "VERTRIEB",
  "idempotency_key": "7d1c2f0e-…"
}'

Esimerkki: joukkokirje

curl -X POST https://mcpbrief.de/api/v1/letters/batch/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipients": [
    {"name": "Muster GmbH", "street": "Ringstraße 5", "zip": "1010",
     "city": "Wien", "country": "AT", "anrede": "Sehr geehrte Frau Huber"},
    {"name": "Beispiel AG", "street": "Hauptstraße 1", "zip": "10115",
     "city": "Berlin", "country": "DE", "anrede": "Sehr geehrte Damen und Herren"}
  ],
  "subject": "Preisanpassung 2027",
  "content": "{{anrede}},\n\nab 1. Jänner gelten neue Preise …",
  "delivery": "standard", "idempotency_key": "batch-2027-01"
}'

Kirjeet sähköpostitse

Ohjelmointia ei tarvita: jokaisella tilillä on henkilökohtainen tilausosoite. PDF-tiedostot, jotka lähetät tilisi sähköpostiosoitteesta tähän osoitteeseen, lähtevät kirjeinä.

Jokainen PDF-liite = yksi kirje, osoite ikkuna-alueella (DIN 5008)
Aiherivi ohjaa asetuksia: Registered, Priority, Colour, Duplex, Ref: …, Country: …
”Enclosure” aiherivillä: kaikki tiedostot yhdistetään yhdeksi kirjeeksi
”Test” aiherivillä: vain tarkistus ja hinta sähköpostitse – mitään ei lähetetä

Tila-arvot

Tilapäätepiste, luettelo ja sähköposti-ilmoitus näyttävät nykyisen tilan.

`pending`	jonossa
`processing`	tulostetaan ja kuoritetaan
`mailed`	jätetty postin kuljetettavaksi
`failed`	ei lähetetty
`cancelled`	peruttu
`undeliverable`	ei voitu toimittaa
`rejected`	hylätty