---
title: "Upload a temporary custom motive"
method: POST
path: "/motives"
tags: ["Motives"]
---

# Upload a temporary custom motive

`POST /motives`

## Request

- Base URL: `https://api.echtpost.de/v2`
- URL: `https://api.echtpost.de/v2/motives`
- 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

Uploads one temporary, account-owned postcard motive. The account must be enabled for API custom motives. The front image must be a readable PNG or JPEG file, at most 5 MB, and exactly 1795x1287 pixels for landscape motives or 1287x1795 pixels for vertical motives. An optional custom back side can be uploaded as a separate `back_side` file when the account has both regular custom back-side bookings active: logo replacement and vertical text replacement. The back side has its own 5 MB limit and must always be exactly 1795x1287 px landscape, independent of `orientation`, because it is printed full-bleed without rotation. When `back_side` is present, EchtPost does not render its standard postmark image or footer logo; the uploaded image must include the franking area, dividing line, footer line, and static branding elements, but not recipient address lines because EchtPost prints the actual address. API clients upload artwork and card data, not the final PDF, and are responsible for checking the final print result in the EchtPost web UI during development. Accounts are limited to 1,000 temporary motive uploads per rolling 24 hours; exceeding that limit returns HTTP 429 and notifies support.

## Response `201`

Created

- Motive
  - `id` integer
  - `name` string
  - `desc` string, nullable
  - `orientation` 'vertical' | 'landscape'
  - `highlight` boolean
  - `content_available` boolean
  - `content_ps_available` boolean
  - `vertical_text_available` boolean
  - `qr_code_available` boolean
  - `has_back_side` boolean: Whether this motive has a custom back-side image attached.
  - `url` string, nullable: Link to the motive page on echtpost.de
  - `preview_image_url` string, uri, nullable: URL to a preview image of the motive front (~300-420px). For your own motives this is a signed asset URL that stays valid until the assets are purged (see assets_purged_at), and anyone holding the link can open the image.
  - `back_side_image_url` string, uri, nullable: URL to a preview image of the custom back side (~300-420px), or null when the motive has no custom back side. Signed asset URL with the same lifetime as preview_image_url.
  - `tags` string[]
  - `temporary` boolean
  - `assets_expires_at` string, date, nullable: Earliest date on which temporary motive assets may be purged. Null for permanent motives or already-purged assets without a pending expiry.
  - `assets_purged_at` string, date-time, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Authentication required
- `422`: Unprocessable Entity
- `429`: Daily temporary motive upload limit exceeded

---

[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)