---
title: "Envoi postal d’une lettre (catalogue ou libre). Clé vf_test_ : simulé, non facturé."
method: POST
path: "/v1/mailings"
tags: ["B2B (v1)"]
---

# Envoi postal d’une lettre (catalogue ou libre). Clé vf_test_ : simulé, non facturé.

`POST /v1/mailings`

## Request

- Base URL: `https://api.vitef.com`
- URL: `https://api.vitef.com/v1/mailings`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string: Rend la requête rejouable sans effet en double pendant 24 h (UUID v4 recommandé). Même clé et même requête : la première réponse est renvoyée avec `Idempotent-Replayed: true`, sans nouvel envoi ni nouveau débit. Même clé pour une autre requête : 422 `idempotency_key_reused`. Requête identique encore en cours : 409 `idempotency_in_progress`.

## Request body

- MailingRequest
  - `letter` string: Slug de la lettre du catalogue.
  - `provider` string: Slug du fournisseur (facultatif).
  - `values` Values: Valeurs du formulaire, par clé de champ.
  - `sender` Sender
    - `name` string
    - `street` string
    - `city` string
  - `doc` object: Lettre libre (IA, sur mesure) : à la place de letter/values.
    - `title` string, required
    - `sender` string[], required
    - `recipient` string[], required
    - `place` string, required
    - `date` string, required
    - `subject` string, required
    - `body` string[], required
    - `signature` string, required
    - `signatureImage` string: Signature dessinée, en data URL PNG (fond transparent conseillé, 200 k caractères au plus). Imprimée au-dessus du nom.
  - `signatureImage` string: Signature dessinée à imprimer sur la lettre (catalogue ou lettre libre).
  - `mode` 'simple' | 'rec' | 'ar', required
  - `reference` string: Votre référence (30 caractères, lettres, chiffres, espace, _ et -).

## Response `201`

Envoi créé

- Shipment
  - `title` string, required
  - `mode` 'simple' | 'rec' | 'ar' | 'lre', required
  - `modeLabel` string, required
  - `status` 'paid' | 'printed' | 'posted' | 'in_transit' | 'delivered' | 'ar_signed' | 'returned' | 'error' | 'canceled', required
  - `statusLabel` string, required
  - `step` integer, required
  - `lastStep` integer, required: 4 (simple, recommandé) ou 5 (recommandé avec AR).
  - `trackingNumber` string
  - `createdAt` string, required
  - `events` ShipmentEvent[], required
    - `step` integer, required: 0 payée, 1 imprimée, 2 remise à La Poste, 3 acheminement, 4 distribuée, 5 AR signé.
    - `status` 'paid' | 'printed' | 'posted' | 'in_transit' | 'delivered' | 'ar_signed' | 'returned' | 'error' | 'canceled', required
    - `label` string, required
    - `at` string, required
  - `id` string, required
  - `orderId` string, nullable, required
  - `recipient` string[], required
  - `recipientEmail` string: LRE : adresse e-mail du destinataire.
  - `amountCents` integer, required
  - `reference` string, nullable, required
  - `test` boolean, required: Envoi simulé (clé vf_test_) : rien n’est posté.
  - `proofs` object[], required: Preuves disponibles (dépôt, accusé de réception…), à télécharger via …/proofs/{kind}.
    - `kind` 'filing' | 'delivery' | 'return' | 'download' | 'rejection' | 'negligence', required
    - `label` string, required
  - `contentProof` object: Recommandé papier (hors API B2B) : preuve de contenu, une fois la lettre remise à La Poste. Gardée 5 ans.
    - `label` string, required
    - `sha256` string, required: Empreinte SHA-256 du document exact remis à l’impression.
    - `url` string, uri, required: Lien signé et durable vers l’attestation PDF.
  - `document` PlainLetter: Lettre entièrement textuelle (sans champ à compléter), telle qu’imprimée et envoyée.
    - `title` string, required
    - `sender` string[], required
    - `recipient` string[], required
    - `place` string, required
    - `date` string, required
    - `subject` string, required
    - `body` string[], required
    - `signature` string, required
    - `signatureImage` string: Signature dessinée, en data URL PNG (fond transparent conseillé, 200 k caractères au plus). Imprimée au-dessus du nom.

## Other responses

- `400`: Requête invalide
- `401`: Authentification requise ou invalide
- `402`: Crédits ou paiement requis
- `403`: Accès refusé (`insufficient_scope`, `account_suspended`, `live_not_enabled`)
- `404`: Ressource introuvable
- `409`: Requête identique encore en cours (`idempotency_in_progress`)
- `413`: Corps trop volumineux (`payload_too_large`)
- `422`: Requête impossible à traiter ; Clé Idempotency-Key déjà utilisée pour une autre requête (`idempotency_key_reused`)
- `429`: Trop de requêtes
- `500`: Erreur interne
- `502`: Service partenaire en erreur
- `503`: Service indisponible

---

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