Introduction

The DRSE API sends real, physical mail. You supply a design and a list of postal addresses; the platform renders one personalised document per recipient, sends it to print, and distributes.

If you have integrated an email service, the model is familiar — lists, recipients, templates, campaigns. One difference governs everything else:

There is no unsend

A campaign that reaches processing is being printed. You cannot recall it, edit it, or stop it. Paper, postage and delivery are all spent. Treat POST /api/v1/campaigns as an irreversible, billable action, and always send an Idempotency-Key so a network retry cannot mail the same batch twice.

The shape of an integration

        ┌─── web app (you, once) ─────┐
        │  design and preview a       │
        │  template  →  templateId    │
        └──────────────┬──────────────┘
                       │
        ┌──────────────▼──────────────────────────────┐
        │  your code (the API)                        │
        │                                             │
        │  1. recipients  ── a saved list, rows in    │
        │                    the request, or a file   │
        │  2. create the campaign  ─────────────────► │
        │  3. poll until completed or failed          │
        └─────────────────────────────────────────────┘

Steps 1–3 are fully programmable. Step 0 — the template — is deliberately not.

What you do in the web app

Design a template. The editor shows exactly what will print, including the zones a postal carrier needs left clear. Mail cannot be proof-read after printing, so a template is signed off visually; your integration then references it by id. See Templates.

Create an API key. Keys are minted on the web app's API page, where you configure the key's permissions.

What your code does

Task	Endpoint
Build a reusable audience	Lists and Recipients
Bulk-load addresses	CSV / Excel import
Send the mail	POST /api/v1/campaigns
Watch it finish	GET /api/v1/campaigns/:id
Add a retargetable QR code	QR codes

Two ways to supply content

Content source	Supported over the API	Why
templateId	Yes — recommended	You previewed the output in the editor before using it
pdf file part	Yes	You rendered the PDF, so its correctness is yours to verify
Raw editor content	No	Nothing has ever displayed it, so nobody can confirm what would be printed

Raw rich-text content is accepted today but is not part of the supported API surface, and will be rejected for API keys in a future release. Build on templateId or pdf. See Campaigns.

Three ways to supply recipients

One call can carry the audience with it, so a simple integration never has to manage lists at all:

Recipient source	Use when
listId	The audience already exists in the platform and gets reused
recipients	You have the addresses in hand, up to 5000 per call. A list is created for you
recipientsFile	You have a CSV or Excel export. A list is created for you

All three validate every row before anything is written. A single bad row means no list, no recipients and no campaign — never a half-sent batch. See Lists & recipients.

Conventions in one minute

• Base URL: https://api.utskick.dr.se — the production API.
• Auth: x-api-key: drse_... on every request.
• Success: { "data": ... }, collections add { "meta": ... }.
• Errors: { "error": { "code", "message", "details?" } } — branch on code.
• 403 always means a permission problem. A resource you cannot see is 404.

Full detail: Conventions.

Next

Fastest path to a letter in the post: Quickstart.

Prefer the model first? Read Campaigns, then Templates.