Envelopify API

1. Sleutel aanmaken. Maak een gratis account, ga naar API-sleutels en kies Testsleutel maken. Vervang in de voorbeelden test_JOUW_SLEUTEL door je sleutel.
2. Testbrief sturen. De aanroep bij Brief versturen gebruikt onze voorbeeld-pdf en werkt zoals hij er staat. Er wordt niets geprint of aangerekend.
3. Status opvragen. Neem het id uit het antwoord en vraag de brief op met GET /api/v1/letters/{id}. Met /pdf erachter zie je de pdf zoals wij hem printen.
4. Statusmeldingen instellen. Registreer een https-link met POST /api/v1/webhooks, dan laten we je weten wanneer je brief geprint en gepost is.
5. Live gaan. Laad tegoed op in het portaal en klik bij je sleutel op Zet live. Nieuwe sleutels starten altijd in testmodus. Je sleutel zelf verandert niet.

Maak een gratis account om je sleutel te maken.

Stuur je sleutel mee in elke aanvraag via de header Authorization: Bearer <sleutel>. Nieuwe sleutels starten in testmodus; je zet ze live in het portaal (API-sleutels, Zet live). De modus hangt aan de sleutel, niet aan het begin van de tekst. Met een sleutel in testmodus worden brieven nooit verstuurd of aangerekend; ze krijgen status received. We tonen een sleutel maar één keer. Bewaar hem als geheim op je server en nooit in browsercode. Een ontbrekende, ongeldige of ingetrokken sleutel geeft 401 unauthorized.

Voor een actieve herinneringsflow met een bewaarde ontvanger. Maakt een eenmalige reeks, niet onmiddellijk een brief. De dagelijkse verwerking gebruikt dezelfde prijs- en stopcontrole. Bij onvoldoende tegoed blijft de gebeurtenis in de wachtrij. event_key voorkomt dubbels per flow en sleutelmodus. Dagmaximum en wachttijd per ontvanger gelden ook in testmodus; testreeksen versturen en kosten niets en worden alleen door een beheerder getest.

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
}

Maakt een brief aan. Geef precies één bron: een pdf (pdf_base64 of pdf_url) of een sjabloon (template_id of template_code) met variables. Bij een pdf geldt je accountkeuze: gratis adresblad vooraan of een wit adresvak op de eerste pagina met options.address_on_first_page. Klein gaat tot 50 g, middel tot 100 g en groot tot 350 g. Middel en groot zijn alleen beschikbaar met een bevestigde, geactiveerde meerprijs. Het adresblad telt mee voor het gewicht, niet voor de basisprijs. Antwoord 201 met id, status, prijs met opsplitsing (price_breakdown), aantal vellen (adresblad inbegrepen), uiterste postdatum volgens de snelheid en test. Met een testsleutel is de status received en post_date leeg. Een geweigerde brief geeft 422 met een foutcode en het letter_id.

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
}

Geeft alle velden van de brief, de tijdstippen, de prijsopsplitsing, het aantal QR-scans (scan_count) en zodra hij gepost is een tijdelijke link naar de foto van de batch (batch_photo_url, 1 uur geldig).

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
}

Geeft de definitieve pdf zoals wij hem printen (application/pdf), met adresblad. Enkel voor je eigen brieven. Een geweigerde brief heeft geen pdf en geeft 404.

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

Geeft je recentste brieven, nieuwste eerst, in data. Is er meer, dan krijg je een next_cursor die je meegeeft als 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..."
}

Annuleert een brief zolang de batch van die dag nog open is. Je tegoed wordt teruggestort en je krijgt de brief terug met status rejected. Is de batch al afgesloten, dan krijg je 409 cutoff_passed.

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

Berekent de prijs van een brief met je huidige schijf, zonder iets aan te maken of af te rekenen. Zelfde opties als een brief, maar met het aantal bedrukte pagina's in plaats van een pdf. Met address_sheet (standaard true) reken je het gratis adresblad mee voor het maximum aantal vellen, zoals bij een opgeladen pdf; zet het op false voor een sjabloonbrief. Niet-geactiveerde gewichtsklassen geven 422 weight_class_unavailable. Met options.address_on_first_page bereken je zonder extra adresblad.

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

Geeft je sjablonen 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"
    }
  ]
}

Maakt een sjabloon. Velden staan tussen dubbele accolades, bv. {{voornaam}}. Een code die al bestaat geeft 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}}."
}'

Geeft je huidig tegoed, je schijf, het aantal echte brieven in de voorbije 30 dagen, hoeveel brieven je nog verwijderd bent van de volgende korting en de prijslijst in cent, excl. btw: prijs per brief per schijf, meerprijzen voor opties en snelheden, en de regels voor express. free_letters_remaining is het aantal gratis proefbrieven dat je nog hebt.

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
}

Geeft de gegevens van je eigen account. company_verified is true als je btw-nummer gecontroleerd is bij de Europese btw-controle (VIES) of door ons manueel. verification_status is verified, none (niet geverifieerd), pending (controle volgt later) of invalid. Bij een geverifieerd bedrijf staan ook official_name en official_address uit het officiële register. GET /balance bevat ook company_verified. De status kan je niet via de API wijzigen: dat gebeurt enkel na een echte controle in het portaal.

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
}

Toont je geregistreerde links en notification_groups. null betekent alle bestaande gebeurtenissen; een lijst beperkt meldingen tot gekozen groepen.

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

Registreert een https-link. Het antwoord bevat eenmalig een secret waarmee je de handtekening controleert.

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_..."
}

Verwijdert een link.

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

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

Bij elke gebeurtenis sturen we een POST naar al je actieve links met { event, letter_id, status, occurred_at, letter }. Elke melding draagt de header x-envelopify-signature: de HMAC-SHA256 (hex) van de ruwe inhoud met je geheim. Controleer die voor je de melding vertrouwt en antwoord met een 2xx-status. Lukt een melding niet (geen 2xx of geen antwoord binnen 8 seconden), dan proberen we ze tot 3 keer opnieuw (bij je volgende gebeurtenis en bij elke productieronde), dus 4 pogingen in totaal. Testbrieven blijven op received en geven geen meldingen.

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

Handtekening controleren:

// 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);

Stuur een header Idempotency-Key mee, bv. je factuurnummer. Stuur je dezelfde sleutel opnieuw, binnen 24 uur, dan krijg je de bestaande brief terug (status 200) in plaats van een nieuwe, en wordt er niets extra aangerekend. Na 24 uur geldt de sleutel als nieuw.

Fouten hebben altijd de vorm { error: { code, message } }. De code (error.code) is altijd dezelfde, in elke taal: gebruik die in je logica. De melding (error.message) is in het Nederlands en mag je zo tonen aan je gebruiker.

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

Maximaal 60 aanvragen per minuut per sleutel. Daarboven krijg je 429 rate_limited en een header Retry-After. Pdf's mogen maximaal 20 MB zijn, een brief maximaal 350 g, middel en groot alleen na activering, maximaal 1.000 expressbrieven per dag en standaard maximaal 1.000 brieven per dag per account. De error.code is taalonafhankelijk en verandert niet; de message is Nederlands. CORS staat open, maar gebruik je sleutel nooit in browsercode.

Eén prijs per brief, excl. btw, alles inbegrepen: 1 vel (enkel- of dubbelzijdig, zwart-wit), envelop, echte postzegels en posten. Volgens je echte brieven in de glijdende voorbije 30 dagen, de nieuwe brief meegeteld, zonder maandreset: €1,29 onder 500, €1,09 vanaf 500, €0,99 vanaf 5.000. Kleur: +€0,08 per vel. Dubbelzijdig zonder meerprijs. Extra vel: +€0,10 per vel bovenop het eerste (dubbelzijdig zijn het twee pagina's per vel). QR-code met scanmeting: +€0,05. Het adresblad is gratis en telt niet mee voor de prijs. Een standaardbrief gaat tot 8 vellen in totaal, adresblad inbegrepen; grotere brieven kunnen op aanvraag via WhatsApp. Snelheden: Standaard (binnen 3 werkdagen verstuurd), Express (+€0,15, zelfde werkdag als aangeleverd vóór 12:00, anders de volgende werkdag) en Flex (€-0,05, binnen 5 werkdagen). Verstuurd betekent: door ons afgegeven aan bpost. bpost bezorgt binnen 2 tot 3 werkdagen na afgifte. Minimum express via de API: zijn je expressbrieven van één dag om 12:00 samen minder dan €15,00, dan houden we het verschil af met de regel "Aanvulling minimum express" in je bewegingen. Je tegoed moet dat bedrag bij het aanmaken al dekken. Maximum 1.000 expressbrieven per dag. Elk antwoord met een prijs bevat price_breakdown met unit_price_cents, tier, volume_30d, letters_to_next_tier, sheets, total_sheets, speed, options (lijst met code, label, amount_cents: extra_sheets, qr_tracking, express, flex) en total_cents. Gratis proefbrieven: elk nieuw account krijgt 3 echte brieven gratis, ook via de API met je sleutel in livemodus. Voorwaarden: snelheid standard, maximaal 3 vellen inhoud, bevestigd e-mailadres en maximaal 3 proefbrieven per ontvangstadres. Een brief die niet voldoet, wordt gewoon van je tegoed betaald. Een proefbrief heeft free_trial: true en price_cents: 0; annuleren voor productie geeft hem terug. GET /balance toont free_letters_remaining. Zware brief: boven 50 g komt er +€0,60 per brief bij (optie heavy_letter). Andere EU-landen: +€1,50 per brief (optie eu), levertermijn 5 tot 10 werkdagen na verzending, geen express. Adrescontrole: bij een Belgisch adres kijken we of de postcode bestaat en bij de gemeente past. Twijfel je antwoord niet weg: de brief krijgt status review met address_warning en wij keuren hem goed of af (tegoed terug).

Alle tarieven en de rekenhulp staan op de prijzenpagina.