API d’envoi de courriers

Du PDF à l’envoi, depuis votre serveur.

Une requête transmet les documents, les adresses et le mode d’envoi. Poste24 organise la suite : impression, mise sous enveloppe et expédition.

Avant votre première requête

  1. Disposez d’un abonnement actif et d’un moyen de paiement enregistré.
  2. Créez une clé dédiée à votre application.
  3. Encodez vos PDF en base64 et renseignez les deux adresses.
Créer une clé

Exemple de requête

Point d’entréehttps://server.poste24.co/api/letters/send

curl --request POST \
  --url https://server.poste24.co/api/letters/send \
  --header "Authorization: Bearer $POSTE24_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "letter": {
    "mode": "tracked",
    "address": {
      "sender": {
        "type": "company",
        "company": "Atelier Exemple",
        "firstName": "Alex",
        "lastName": "Martin",
        "address": "10 rue des Lilas",
        "zipCode": "75001",
        "city": "Paris",
        "country": "France"
      },
      "recipient": {
        "type": "individual",
        "title": "Mrs",
        "firstName": "Camille",
        "lastName": "Durand",
        "address": "25 rue des Fleurs",
        "zipCode": "69001",
        "city": "Lyon",
        "country": "France"
      }
    },
    "content": {
      "files": [
        {
          "name": "courrier.pdf",
          "base64": "JVBERi0xLjQK..."
        }
      ]
    }
  }
}'

Dans cet exemple, sender et recipient reprennent les deux objets complets de l’exemple cURL. Remplacez le PDF de démonstration par un vrai document avant un envoi ; toute requête acceptée est payante.

Authentification

Transmettez la clé en Bearer dans l’en-tête Authorization. Les clés Poste24 commencent par poste24_api_key_. Ne les placez jamais dans du JavaScript envoyé au navigateur.

Structure d’une demande

Le corps JSON contient un objet letter. Les noms de champs et les valeurs techniques ci-dessous doivent rester inchangés.

L’envoiletter
modestring
Obligatoire: Ouiuntracked : lettre verte ; tracked : lettre suivie ; certified : recommandé avec AR.
address.senderobject
Obligatoire: OuiAdresse de l’expéditeur.
address.recipientobject
Obligatoire: OuiAdresse du destinataire.
contentobject
Obligatoire: OuiDocuments PDF à transmettre.
Les adressesletter.address.sender / letter.address.recipient
typestring
Obligatoire: Ouiindividual ou company.
titlestring
Obligatoire: Pour un particulierCivilité : Mr ou Mrs. 12 caractères maximum.
companystring
Obligatoire: Pour une entrepriseRaison sociale : 90 caractères maximum.
firstNamestring
Obligatoire: Pour un particulierPrénom : 70 caractères maximum.
lastNamestring
Obligatoire: Pour un particulierNom : 70 caractères maximum.
addressstring
Obligatoire: OuiNuméro et voie : 90 caractères maximum.
additionalAddressstring
Obligatoire: NonComplément : 90 caractères maximum.
zipCodestring
Obligatoire: OuiCode postal : 12 caractères maximum.
citystring
Obligatoire: OuiVille : 70 caractères maximum.
countrystring
Obligatoire: OuiNom du pays, par exemple France : 70 caractères maximum.
Les documentsletter.content
filesobject[]
Obligatoire: NonDocuments principaux. Au moins un document requis au total.
attachmentsobject[]
Obligatoire: NonPièces jointes, avec la même structure que files.
Un fichier PDFfiles[] / attachments[]
namestring
Obligatoire: NonNom du fichier, par exemple courrier.pdf.
base64string
Obligatoire: OuiPDF encodé en base64 brut, sans préfixe data:. 10 Mo maximum après décodage.

Comprendre la réponse

Une réponse HTTP 200 confirme l’acceptation du traitement et du paiement, pas la distribution du courrier. Conservez la référence renvoyée pour retrouver l’envoi dans votre espace client.

{
  "reference": 1723385280000,
  "status": "accepted",
  "amount": 1.01,
  "currency": "EUR"
}

En cas d’erreur

Les rejets renvoient actuellement un statut HTTP 500 et un champ message. Les messages des prestataires de paiement ou de stockage peuvent varier. En cas de délai dépassé ou de réponse ambiguë, vérifiez l’historique avant de renvoyer : une nouvelle requête peut créer un doublon payant.

INVALID_API_KEY
Clé invalide, révoquée ou désactivée (abonnement résilié ou expiré).
Invalid letter
Mode, adresse ou nombre de documents invalide.
Invalid PDF documents
Document non PDF, données invalides ou taille dépassée.