---
title: "Create a card (custom)"
method: POST
path: "/cards"
tags: ["Cards"]
---

# Create a card (custom)

`POST /cards`

## Request

- Base URL: `https://api.echtpost.de/v2`
- URL: `https://api.echtpost.de/v2/cards`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://my.echtpost.de/oauth/authorize`, token URL `https://my.echtpost.de/oauth/token`, scopes: `mcp`)
  - API key in header `X-Api-Key`
  - HTTP bearer

## Request body

- object
  - `motive_id` integer, required
  - `content` string, required: Card text. Use {anrede} as a per-recipient salutation placeholder (casing ignored).
  - `content_ps` string: Optional P.S., printed as a single footer line.
  - `content_vertical` string
  - `deliver_at` string: Delivery date. Accepts: ISO 8601 date (`YYYY-MM-DD`), `today`, `asap` (alias for today), `tomorrow`, or `N-days-from-now` (e.g. `5-days-from-now`). Must resolve to a weekday that is not a printer holiday. Must be at most 90 days in the future. Omitting this field schedules the card for the next available business day.
  - `qr_code_url` string
  - `deduplicate_recipients` boolean
  - `recipient_ids` integer[]
  - `group_ids` integer[]
  - `recipients` RecipientInput[]
    - `first_name` string
    - `last_name` string, required
    - `title` string
    - `greeting_style` 'formal' | 'informal' | 'custom'
    - `custom_salutation` string
    - `gender` string
    - `company_name` string
    - `department` string
    - `street` string, required
    - `zip` string, required
    - `city` string, required
    - `state_code` string
    - `country_code` string, required
    - `birthdate` string, date
    - `external_id` string
  - `font` Font
    - `family` string: Font slug. Allowed `architects_daughter`, `reenie_beanie`, `special_elite`.
    - `size` integer: Absolute font size. Valid ranges per family — `architects_daughter` 12..14, `reenie_beanie` 15..17, `special_elite` 11..13.
    - `color` string: `black`, `blue`, or a hex value.
    - `line_height` number
  - `notifications` Notification[]
    - `type` 'after_sent' | 'before_send', required: `after_sent` mails `email` once the card is sent. `before_send` mails a reminder on `send_on`.
    - `email` string, email, required
    - `send_on` string, date: `before_send` only. Reminder date, on or before the send date. Defaults to the send date. Ignored for `after_sent`.
  - `notification` Notification
    - `type` 'after_sent' | 'before_send', required: `after_sent` mails `email` once the card is sent. `before_send` mails a reminder on `send_on`.
    - `email` string, email, required
    - `send_on` string, date: `before_send` only. Reminder date, on or before the send date. Defaults to the send date. Ignored for `after_sent`.
  - `simulate` 'insufficient_funds': Sandbox only. Instead of creating the card, force a simulated error so API clients can test their error handling. `insufficient_funds` returns HTTP 402 with the normal insufficient-funds body. Ignored with a live key.

## Response `201`

Created

- Card
  - `id` string, uuid
  - `account_id` integer
  - `user_id` integer
  - `motive_id` integer
  - `template_id` integer, nullable
  - `status` 'pending' | 'scheduled' | 'sent' | 'canceled'
  - `type` 'CardSingle' | 'CardMulti'
  - `content` string
  - `content_ps` string, nullable
  - `content_vertical` string, nullable
  - `font` Font
    - `family` string: Font slug. Allowed `architects_daughter`, `reenie_beanie`, `special_elite`.
    - `size` integer: Absolute font size. Valid ranges per family — `architects_daughter` 12..14, `reenie_beanie` 15..17, `special_elite` 11..13.
    - `color` string: `black`, `blue`, or a hex value.
    - `line_height` number
  - `contacts_count` integer
  - `deliver_at` string, date-time, nullable
  - `qr_code_url` string, nullable
  - `cancelable` boolean
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Authentication required
- `402`: Payment Required — insufficient funds
- `422`: Unprocessable Entity — validation, text-does-not-fit, invalid-delivery-date, feature-not-available

---

[API](https://skmtc.dev/echtpost/apis/echtpost-api.md) · [All operations](https://skmtc.dev/echtpost/apis/echtpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/echtpost/apis/echtpost-api/revisions/6935f24e4c33?raw)