API, trộn thư & gửi qua email

Gửi thư trực tiếp từ phần mềm của bạn – qua REST API, dưới dạng trộn thư hoặc đơn giản bằng email. Connector Claude dùng cùng các chức năng này.

Xác thực

Tạo khóa tại Tài khoản → Khóa API và gửi dưới dạng bearer token. Mỗi yêu cầu chỉ trừ vào số dư của tài khoản đó.

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

Mô tả OpenAPI: https://mcpbrief.de/openapi.json

Endpoint

GET	/balance	Số dư, giá, người gửi, giới hạn ngày
POST	/letter/price	Kiểm tra địa chỉ, tạo thư, số trang và giá + bản xem trước PDF (không gửi gì)
POST	/letter/send	Gửi thư (văn bản, PDF, DOCX, hình ảnh; tài liệu kèm theo, in hai mặt, trung tâm chi phí)
GET	/letter/{id}	Trạng thái và mã theo dõi
POST	/letter/{id}/cancel	Hủy trước khi in (hoàn tiền)
POST	/letter/{id}/resend	Gửi lại
GET	/letters?limit=&status=&since=&cost_center=&batch_id=	Danh sách thư của bạn, có thể lọc
POST	/letters/batch/price	Kiểm tra trộn thư: tất cả địa chỉ, placeholder, tổng giá
POST	/letters/batch/send	Gửi trộn thư (tối đa 200 người nhận)

Ví dụ: thư bảo đảm kèm tài liệu

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-…"
}'

Ví dụ: trộn thư

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"
}'

Thư qua email

Không cần lập trình: mỗi tài khoản có một địa chỉ đặt hàng riêng. PDF bạn gửi từ email tài khoản đến địa chỉ này sẽ được gửi đi thành thư.

Mỗi PDF đính kèm = một lá thư, địa chỉ trong vùng cửa sổ (DIN 5008)
Tiêu đề email điều khiển tùy chọn: Registered, Priority, Colour, Duplex, Ref: …, Country: …
“Enclosure” trong tiêu đề: tất cả tệp được gộp thành một lá thư
“Test” trong tiêu đề: chỉ kiểm tra và nhận giá qua email – không gửi gì

Giá trị trạng thái

Endpoint trạng thái, danh sách và thông báo email hiển thị tình trạng hiện tại.

`pending`	đang chờ
`processing`	đang in & đóng phong bì
`mailed`	đã chuyển cho bưu điện
`failed`	chưa gửi
`cancelled`	đã hủy
`undeliverable`	không thể phát
`rejected`	bị từ chối