Bjet24 API: trigger a postal mailing from your CRM in a few lines of code

When postal mail must be triggered from your app

Many paper mailings are consequences of a business event: a signed contract, an invoice 30 days overdue, a legal notice, a changed insured party. Asking a human to "remember" to draft a letter after each event invites forgetfulness and delay.

The Bjet24 API exists exactly for that: your application triggers the mailing, Bjet24 prints, stuffs the envelope and hands it to bpost, with proofs flowing back. Check the pricing page for a breakdown of costs by mail type.

Flow overview

The lifecycle of an API mailing covers four steps:

1. You create a job with the PDF, the recipient and the mail type.
2. The job moves through draft → paid → queued → printed → posted → delivered.
3. You receive a webhook at every major status change (payment, bpost handover, proof of delivery).
4. At any time, you can fetch the job to retrieve the PDF proofs (proof of posting, return receipt, etc.).

This is a classic async pattern — the calling app does not block waiting for distribution.

Authentication

The API uses an API key passed as Authorization: Bearer <key>. Keys are created in your Bjet24 account, scoped to an environment (sandbox or production) and individually revocable.

Good habit: one key per integration (CRM, ERP, internal tool). When something goes wrong, revoke one key without breaking the others. Before going live, also review Belgian postal address verification best practices to reduce rejected deliveries.

Creating a mailing in TypeScript

A typical call to send a standard letter. The PDF is referenced by a file ID you uploaded earlier through an upload endpoint:

const res = await fetch("https://api.bjet24.com/v1/mail-jobs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BJET24_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "standard",            // or "registered"
    priority: "prior",           // or "non-prior"
    documentId: "doc_abc123",    // PDF previously uploaded
    recipient: {
      name: "Dupont Ltd",
      street: "Rue de la Loi",
      number: "12",
      box: "3",
      zip: "1000",
      city: "Brussels",
      country: "BE",
    },
  }),
})

const job = await res.json()
console.log("job created:", job.id, job.status)

Typical response:

{
  "id": "job_01HE...",
  "status": "draft",
  "type": "standard",
  "priority": "prior",
  "amount": { "value": 195, "currency": "EUR" },
  "createdAt": "2026-03-20T10:14:22.000Z"
}

At this point the job is in draft. To confirm it, you pay through your pre-loaded wallet or Stripe, which moves it to paid → queued.

Receiving events via webhooks

Instead of polling, you subscribe an endpoint to receive events. Typical payload:

{
  "id": "evt_...",
  "type": "mail_job.posted",
  "createdAt": "2026-03-21T08:02:11.000Z",
  "data": {
    "id": "job_01HE...",
    "status": "posted",
    "bpostTrackingId": "EE...BE",
    "proofs": {
      "deposit": "https://api.bjet24.com/v1/proofs/.../deposit.pdf"
    }
  }
}

The events to know:

• mail_job.paid — payment captured,
• mail_job.printed — item printed,
• mail_job.posted — handed to bpost (proof of posting available),
• mail_job.delivered — delivered (registered only, proof of delivery available),
• mail_job.failed — returned or rejected (invalid address, refusal).

Don't forget to verify the HMAC signature sent in the X-Bjet24-Signature header. That's your defence against spoofed webhooks. The Bjet24 webhooks tutorial for real-time delivery tracking walks through a complete implementation.

Three useful integration patterns

1) Automatic D+30 reminders (CRM/billing). A scheduled task scans your unpaid invoices whose due date is more than 30 days old and creates a registered job with return receipt, pre-filled from your PDF template. Companies sending high volumes can also explore bulk mailing options for Belgian businesses.

2) Onboarding confirmation (insurance, banking). On e-signature of a contract, the webhook from your e-sign tool calls the Bjet24 API to send the paper copy to the customer — required by some regulators.

3) Regulatory notification (HR, real estate). On every business event that opens a deadline (notice, dispute), you create a job immediately, archive the jobId in your database and keep the proof of posting as supporting evidence.

Sandbox, idempotency and limits

A few best practices to stay out of trouble:

• Sandbox: use the test key for all development work. Jobs follow the same cycle but are not actually printed.
• Idempotency-Key: pass an Idempotency-Key header tied to your business event. If your worker retries, you don't create two mailings.
• Rate limits: the public API has a reasonable quota (see the documentation). For pro volumes, use the bulk endpoint that accepts a CSV in a single call.

Summary

The Bjet24 API turns every business-event trigger into a traceable postal mailing, with no manual intervention. For a CRM or ERP integration, count one to two days of development for the first version (job creation + webhook). The ROI is mostly about reliability: no missed letters, no mail sleeping on a desk, and every proof archived in the right place.