Envelopify API

1. Create a key. Create a free account, open API-sleutels (API keys) and create a test key. Replace test_YOUR_KEY in the examples.
2. Send a test letter. The example under Send a letter uses our sample PDF and works as is. Nothing is printed or charged.
3. Check the status. Take the id from the response and call GET /api/v1/letters/{id}. Add /pdf to get the PDF exactly as we print it.
4. Set up webhooks. Register an https URL with POST /api/v1/webhooks to be notified when a letter is printed and posted.
5. Go live. Top up credit in the portal and click Go live next to your key. New keys always start in test mode. The key itself does not change.

Create a free account to create your key.

Send your key with every request in the header Authorization: Bearer <key>. New keys start in test mode; you switch them live in the portal (API keys, Go live). The mode belongs to the key, not to its prefix. With a key in test mode letters are never printed, sent or charged; they get status received. A key is shown only once: store it as a server-side secret, never in browser code. A missing, invalid or revoked key returns 401 unauthorized.

For an active reminder flow and saved contact. Queues a one-time plan, not an immediate letter. Daily processing uses shared pricing and stop checks; insufficient credit retains the queue entry. event_key deduplicates per flow and key mode. Daily and recipient cooldown limits apply; test plans are admin-executed only and never send or charge.

curl -X POST https://envelopify.lovable.app/api/v1/flow-events \
  -H "Authorization: Bearer test_JOUW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
  "flow_id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
  "contact_id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
  "event_key": "herinnering-104",
  "variables": {}
}'

{
  "status": "queued",
  "test": true
}

Creates a letter. Provide exactly one source: a PDF (pdf_base64 or pdf_url) or a template (template_id or template_code) with variables. PDFs follow the account default: a free address sheet or a white address box on page one using options.address_on_first_page. Small is up to 50 g, medium up to 100 g and large up to 350 g. Medium and large require a confirmed and enabled surcharge. The address sheet counts for weight, not the base price. Returns 201 with id, status, price with breakdown (price_breakdown), sheet count (address sheet included), latest post date for the chosen speed and test. With a test key the status is received and post_date is null. A rejected letter returns 422 with an error code and letter_id. Optional header Idempotency-Key.

curl -X POST https://envelopify.lovable.app/api/v1/letters \
  -H "Authorization: Bearer test_JOUW_SLEUTEL" \
  -H "Idempotency-Key: factuur-2026-104" \
  -H "Content-Type: application/json" \
  -d '{
  "recipient": {
    "name": "An Peeters",
    "street": "Meir",
    "number": "12",
    "postal_code": "2000",
    "city": "Antwerpen"
  },
  "pdf_url": "https://envelopify.lovable.app/voorbeeld.pdf",
  "options": {
    "color": false
  },
  "reference": "factuur-2026-104"
}'

{
  "id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
  "status": "scheduled",
  "price_cents": 129,
  "price_breakdown": {
    "unit_price_cents": 129,
    "tier": 1,
    "tier_fixed": false,
    "volume_30d": 120,
    "letters_to_next_tier": 379,
    "pages": 1,
    "sheets": 1,
    "address_sheet": true,
    "total_sheets": 2,
    "color": false,
    "duplex": false,
    "speed": "standard",
    "destination": "BE",
    "options": [],
    "total_cents": 129,
    "on_request": false,
    "currency": "EUR",
    "vat_included": false
  },
  "sheet_count": 2,
  "post_date": "2026-11-13",
  "free_trial": false,
  "test": false
}

Returns all letter fields, timestamps, the price breakdown, the number of QR scans (scan_count) and, once posted, a temporary link to the batch photo (batch_photo_url, valid 1 hour).

curl -X GET https://envelopify.lovable.app/api/v1/letters/b1d1a7f7-3db2-43df-a896-bc9dc10c6029 \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
  "tracking_code": "B1D1A7F7",
  "reference": "factuur-2026-104",
  "status": "posted",
  "test": false,
  "reject_reason": null,
  "return_reason": null,
  "recipient": {
    "company": null,
    "name": "An Peeters",
    "street": "Meir",
    "number": "12",
    "box": null,
    "postal_code": "2000",
    "city": "Antwerpen",
    "country": "BE"
  },
  "source": "pdf",
  "color": false,
  "duplex": false,
  "qr_tracking": false,
  "sheet_count": 2,
  "price_cents": 129,
  "price_breakdown": {
    "unit_price_cents": 129,
    "tier": 1,
    "tier_fixed": false,
    "volume_30d": 120,
    "letters_to_next_tier": 379,
    "pages": 1,
    "sheets": 1,
    "address_sheet": true,
    "total_sheets": 2,
    "color": false,
    "duplex": false,
    "speed": "standard",
    "destination": "BE",
    "options": [],
    "total_cents": 129,
    "on_request": false,
    "currency": "EUR",
    "vat_included": false
  },
  "speed": "standard",
  "post_deadline": "2026-11-13",
  "created_at": "2026-11-12T10:02:11Z",
  "scheduled_at": "2026-11-12T10:02:11Z",
  "printed_at": "2026-11-13T09:40:00Z",
  "posted_at": "2026-11-13T16:02:11Z",
  "returned_at": null,
  "post_date": "2026-11-13",
  "scan_count": 0,
  "batch_photo_url": null
}

Returns the final PDF exactly as we print it (application/pdf), including the address sheet. Only for your own letters. A rejected letter has no PDF and returns 404.

curl -X GET https://envelopify.lovable.app/api/v1/letters/b1d1a7f7-3db2-43df-a896-bc9dc10c6029/pdf \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

Returns your most recent letters, newest first, in data. When there are more, pass next_cursor back as cursor.

curl -X GET https://envelopify.lovable.app/api/v1/letters?status=posted&limit=50 \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "data": [
    {
      "id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
      "status": "posted",
      "reference": "factuur-2026-104"
    }
  ],
  "next_cursor": "MjAyNi0xMS0xMlQxMDo..."
}

Cancels a letter while the batch of that day is still open. The amount is credited back to your Envelopify balance, not paid out and the letter is returned with status rejected. Once the batch is closed you get 409 cutoff_passed.

curl -X DELETE https://envelopify.lovable.app/api/v1/letters/b1d1a7f7-3db2-43df-a896-bc9dc10c6029 \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

Calculates the price of a letter with your current tier, without creating or charging anything. Same options as a letter, but with the number of printed pages instead of a PDF. address_sheet (default true) counts the free address sheet towards the sheet limit, like an uploaded PDF; set it to false for a template letter. Unavailable weight bands return 422 weight_class_unavailable. Use options.address_on_first_page to exclude the extra address sheet.

curl -X POST https://envelopify.lovable.app/api/v1/price \
  -H "Authorization: Bearer test_JOUW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
  "pages": 3,
  "address_sheet": true,
  "options": {
    "color": false,
    "duplex": false,
    "qr_tracking": false,
    "speed": "standard"
  }
}'

{
  "price_breakdown": {
    "unit_price_cents": 129,
    "tier": 1,
    "tier_fixed": false,
    "volume_30d": 120,
    "letters_to_next_tier": 379,
    "pages": 3,
    "sheets": 3,
    "address_sheet": true,
    "total_sheets": 4,
    "color": false,
    "duplex": false,
    "speed": "standard",
    "destination": "BE",
    "options": [
      {
        "code": "extra_sheets",
        "label": "Extra vellen (2)",
        "amount_cents": 20
      }
    ],
    "total_cents": 149,
    "on_request": false,
    "currency": "EUR",
    "vat_included": false
  }
}

Returns your templates in data.

curl -X GET https://envelopify.lovable.app/api/v1/templates \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "data": [
    {
      "id": "6c1f...",
      "name": "Herinnering",
      "code": "herinnering",
      "body": "Beste {{voornaam}}, ...",
      "created_at": "2026-11-12T10:00:00Z"
    }
  ]
}

Creates a template. Fields go between double curly braces, e.g. {{voornaam}}. An existing code returns 409 conflict.

curl -X POST https://envelopify.lovable.app/api/v1/templates \
  -H "Authorization: Bearer test_JOUW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Herinnering",
  "code": "herinnering",
  "body": "Beste {{voornaam}},\n\nWe ontvingen nog geen betaling van {{bedrag}}."
}'

Returns your credit, free trial letters left (free_letters_remaining), current tier, number of real letters in the past 30 days, letters to the next discount and the price list in cents, excl. VAT: price per letter per tier, option surcharges, speeds and the express rules.

curl -X GET https://envelopify.lovable.app/api/v1/balance \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "credit_cents": 4950,
  "free_letters_remaining": 3,
  "company_verified": true,
  "tier": 1,
  "tier_fixed": false,
  "volume_30d": 120,
  "letters_to_next_tier": 380,
  "unit_price_cents": 129,
  "tiers": [
    {
      "tier": 1,
      "from": 0,
      "unit_price_cents": 129
    },
    {
      "tier": 2,
      "from": 500,
      "unit_price_cents": 109
    },
    {
      "tier": 3,
      "from": 5000,
      "unit_price_cents": 99
    }
  ],
  "options": {
    "extra_sheet_cents": 10,
    "qr_tracking_cents": 5
  },
  "speeds": [
    {
      "speed": "standard",
      "name": "Standaard",
      "amount_cents": 0,
      "working_days": 3
    },
    {
      "speed": "express",
      "name": "Express",
      "amount_cents": 15,
      "working_days": 0
    },
    {
      "speed": "flex",
      "name": "Flex",
      "amount_cents": -5,
      "working_days": 5
    }
  ],
  "express": {
    "minimum_cents": 1500,
    "max_letters_per_day": 1000,
    "before_hour": 12
  },
  "heavy_letter": {
    "from_grams": 50,
    "amount_cents": 60
  },
  "eu": {
    "surcharge_cents": 150,
    "countries": [
      "AT",
      "DE",
      "FR",
      "NL",
      "..."
    ],
    "delivery": "5 tot 10 werkdagen na verzending",
    "express": false
  },
  "daily_letter_max": 1000,
  "max_sheets": 8,
  "currency": "EUR",
  "vat_included": false
}

Returns your own account details. company_verified is true when your VAT number has been checked with the EU VAT check (VIES) or manually by us. verification_status is verified, none, pending (check will follow later) or invalid. For a verified company, official_name and official_address come from the official register. GET /balance also includes company_verified. You cannot change the status through the API: it only changes after a real check in the portal.

curl -X GET https://envelopify.lovable.app/api/v1/account \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "customer_id": "4f6c2a1e-...",
  "company": "Jouw Bedrijf",
  "email": "post@jouwbedrijf.be",
  "company_verified": true,
  "verification_status": "verified",
  "vat_number": "BE0123456749",
  "official_name": "Jouw Bedrijf BV",
  "official_address": "Kerkstraat 1\n2000 Antwerpen",
  "checked_at": "2026-11-12T10:00:00Z",
  "free_letters_remaining": 3
}

Lists your registered URLs and notification_groups. null means all existing events; an array limits notifications to selected groups.

curl -X GET https://envelopify.lovable.app/api/v1/webhooks \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "data": [
    {
      "id": "a3c2...",
      "url": "https://jouwsite.be/hooks/envelopify",
      "active": true,
      "created_at": "2026-11-12T10:00:00Z"
    }
  ]
}

Registers an https URL. The response contains the secret once; use it to verify signatures.

curl -X POST https://envelopify.lovable.app/api/v1/webhooks \
  -H "Authorization: Bearer test_JOUW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://jouwsite.be/hooks/envelopify"
}'

{
  "id": "a3c2...",
  "url": "https://jouwsite.be/hooks/envelopify",
  "active": true,
  "created_at": "2026-11-12T10:00:00Z",
  "secret": "whsec_..."
}

Deletes a webhook.

curl -X DELETE https://envelopify.lovable.app/api/v1/webhooks/a3c2... \
  -H "Authorization: Bearer test_JOUW_SLEUTEL"

{
  "id": "a3c2...",
  "deleted": true
}

On every event we POST { event, letter_id, status, occurred_at, letter } to all your active webhook URLs. Each request carries the header x-envelopify-signature: the hex HMAC-SHA256 of the raw body with your secret. Verify it before trusting the payload and answer with a 2xx status. Failed deliveries (no 2xx or no answer within 8 seconds) are retried up to 3 times (on your next event and on every production round), so 4 attempts in total. Test letters stay received and send no webhooks.

{
  "event": "letter.posted",
  "letter_id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
  "status": "posted",
  "occurred_at": "2026-11-13T16:02:12Z",
  "letter": {
    "id": "b1d1a7f7-3db2-43df-a896-bc9dc10c6029",
    "tracking_code": "B1D1A7F7",
    "reference": "factuur-2026-104",
    "status": "posted",
    "posted_at": "2026-11-13T16:02:11Z"
  },
  "created_at": "2026-11-13T16:02:12Z"
}

Verify the signature:

// Node 18+ with Express: verify a webhook signature
import crypto from "node:crypto";
import express from "express";

const SECRET = "whsec_JOUW_GEHEIM"; // returned once when you create the webhook
const app = express();

app.post("/hooks/envelopify", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const given = req.get("x-envelopify-signature") ?? "";
  const ok = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.status(401).end();
  const { event, letter } = JSON.parse(req.body.toString("utf8"));
  console.log(event, letter.id, letter.status);
  res.status(200).end();
});

app.listen(3000);

Send an Idempotency-Key header, e.g. your invoice number. Sending the same key again within 24 hours returns the existing letter (status 200) instead of creating a new one, and nothing extra is charged. After 24 hours the key counts as new.

Errors always have the shape { error: { code, message } }. The code (error.code) is always the same, whatever the language: use it in your logic. The message (error.message) is in Dutch and can be shown to your user as is.

{
  "error": {
    "code": "address_incomplete",
    "message": "Een Belgische postcode bestaat uit 4 cijfers"
  }
}

Max 60 requests per minute per key; above that you get 429 rate_limited with a Retry-After header. PDFs up to 20 MB, letters up to 350 g, medium and large only when enabled, max 1000 express letters per day and by default max 1000 letters per day per account. error.code is language-independent and stable; message is in Dutch. CORS is open, but never use your key in browser code.

One price per letter, excl. VAT, everything included: 1 sheet (single or double-sided, black and white), envelope, real stamps and posting. By your real letters in a rolling 30-day window, including the new letter (no monthly reset): €1,29 under 500, €1,09 from 500, €0,99 from 5000. Colour: +€0,08 per sheet. Double-sided has no surcharge. Extra sheet: +€0,10 per sheet after the first (double-sided is two pages per sheet). QR code with scan tracking: +€0,05. The address sheet is free and not counted for the price. A standard letter holds up to 8 sheets in total, address sheet included; larger letters on request. Speeds (options.speed): standard (handed to bpost within 3 working days), express (+€0,15, same working day when received before 12:00 Europe/Brussels, otherwise the next working day) and flex (€-0,05, within 5 working days). bpost delivers within 2 to 3 working days after hand-over. Express minimum via the API: if your express letters of one day total less than €15,00 at 12:00, the difference is charged as a ledger line "Aanvulling minimum express"; your credit must cover it when creating the letter. Max 1000 express letters per day (422 express_limit). Examples, tier 1: 1 sheet €1,29; 1 sheet colour €1,37; 3 sheets €1,49; 4 pages double-sided (2 sheets) €1,39; with QR €1,34; express €1,44; flex €1,24. Quotes are estimates for the next real letter; simultaneous orders recheck their tariff atomically. Test letters never count. Every response with a price contains price_breakdown with unit_price_cents, tier, volume_30d, letters_to_next_tier, sheets, total_sheets, speed, options (list of code, label, amount_cents) and total_cents. Prices can change; read them from GET /balance or POST /price. Free trial letters: every new account gets 3 real letters for free, also through the API with your key in live mode. Conditions: speed standard, at most 3 content sheets, confirmed e-mail address and at most 3 trial letters per recipient address. A letter that does not qualify is paid from your credit as usual. A trial letter has free_trial: true and price_cents: 0; cancelling before production gives it back. GET /balance shows free_letters_remaining. Heavy letter: above 50 g we add +€0,60 per letter (option heavy_letter). Other EU countries: +€1,50 per letter (option eu), delivery 5 to 10 working days after dispatch, no express. Address check: for a Belgian address we check that the postal code exists and matches the municipality. When in doubt the letter gets status review with address_warning and we approve or reject it (credit refunded).

All rates and the calculator are on the pricing page.