Envoyer du courrier papier depuis votre application : guide d'API

Une API d'impression et de postage transforme une requête HTTP en lettre physique : vous transmettez le destinataire, l'expéditeur et le contenu, et une imprimante quelque part produit du papier qui entre dans le réseau postal. Elle vaut le détour dans les cas précis où le courriel ne suffit pas.

Quand le papier bat le courriel

• Le courriel a rebondi. Les adresses postales se périment beaucoup plus lentement que les adresses de courriel. Pour la reconquête de clients et le recouvrement, la poste rejoint des gens que votre liste a perdus.
• La réglementation impose le papier.De nombreux avis légaux ou réglementaires exigent encore la poste, et un dossier de pourriels n'est pas une défense.
• Vous devez être lu. Une lettre affronte quatre autres enveloppes ; un courriel en affronte trois cents.

Ce à quoi elle ne convient pas, c'est l'urgence. La livraison au Canada prend maintenant de trois à sept jours ouvrables. Si l'envoi doit arriver demain, la poste est le mauvais canal, quelle que soit la qualité de l'API.

À quoi ressemble une requête

La forme est comparable d'un fournisseur à l'autre : on s'authentifie avec une clé, on décrit les deux adresses, on fournit le contenu, on reçoit un identifiant. La nôtre accepte des champs structurés, du HTML brut ou un PDF encodé en base64 :

curl -X POST https://sendletter.app/api/v1/send \
  -H "Authorization: Bearer sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "draft",
    "letter_size": "standard",
    "from": {
      "name": "Acme inc.",
      "line1": "100 rue Queen O",
      "city": "Toronto",
      "province": "ON",
      "postal_code": "M5H 2N2",
      "country": "CA"
    },
    "to": {
      "name": "Jeanne Tremblay",
      "line1": "1 rue Sainte-Catherine",
      "city": "Montreal",
      "province": "QC",
      "postal_code": "H2X 1K4",
      "country": "CA"
    },
    "letter": {
      "salutation": "Madame Tremblay,",
      "body": "Votre abonnement se renouvelle le 1er septembre.",
      "closing": "Cordialement,",
      "signature": "Facturation Acme"
    }
  }'

Quatre pièges d'une première intégration

1. Une reprise imprime du vrai papier.C'est le piège principal. Un appel repris après un échec partiel peut produire deux lettres physiques, et vous ne pouvez pas rappeler la seconde. Générez une clé d'idempotence par lettre logique et enregistrez l'identifiant retourné avant toute reprise.

2. Les adresses échouent tard. Un courriel invalide rebondit en quelques secondes. Une adresse postale erronée échoue des jours plus tard, en silence, et souvent sans vous prévenir. Validez le format du code postal en amont — au Canada, lettre-chiffre-lettre chiffre-lettre-chiffre — et indiquez toujours une adresse de retour, sans quoi le courrier non distribuable est détruit au lieu de revenir.

3. Le nombre de pages change le prix et l'enveloppe.Une enveloppe pour pli en trois contient quelques feuilles ; au-delà, vous passez à une enveloppe à plat, à un tarif supérieur. Si votre contenu vient des utilisateurs, sa longueur devient une donnée de facturation. Comptez les pages avant l'envoi, pas après.

4. Le coût unitaire est tout le modèle de coûts.Il n'y a pas de gratuité en physique. L'affranchissement et l'impression posent un plancher dur sous chaque lettre : la rentabilité unitaire compte ici comme elle ne compte jamais pour le courriel. Vérifiez si un fournisseur ajoute des frais de plateforme ou un minimum mensuel par-dessus le prix unitaire.

Choisir un fournisseur

Soyez honnête sur votre créneau. Si vous menez des campagnes de publipostage en masse, avec segmentation d'auditoire, validation d'adresses à grande échelle et analyse par campagne, les plateformes établies — Lob et PostGrid notamment — sont conçues exactement pour cela et c'est vers elles qu'il faut aller.

Pour le schéma complet des requêtes et des réponses, les codes d'erreur et les deux autres modes de contenu, consultez la référence de l'API.