Référence API

API REST pour le courrier électronique transactionnel

L'API accepte les requêtes authentifiées, vérifie la portée du projet et l'état du domaine, contrôle la suppression, puis met en file d'attente les messages acceptés.

2026-10-13Télécharger OpenAPI 3.1

Authentification

POST /v1/emails

Requête / Réponse

curl --request POST 'https://api.srs-postline.com/v1/emails' \
  --header 'Authorization: Bearer srs_live_...' \
  --header 'Idempotency-Key: order_4821' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "Postline <info@example.com>",
    "to": ["user@example.net"],
    "subject": "Your order is ready",
    "html": "<p>Order #4821 is ready.</p>",
    "text": "Order #4821 is ready."
  }'

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "msg_01JPOSTLINEEXAMPLE",
  "status": "queued",
  "created_at": "2026-08-22T12:00:00Z"
}

Paramètres d’entrée

Paramètre	Type	Requis	Description	Exemple
`Authorization`	`header · string`	Oui	Clé API à portée limitée émise par le tableau de bord sous forme de jeton Bearer.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	Non	Identifiant stable pour un envoi logique ; fortement recommandé.	`order_4821`
`from`	`string`	Oui	Nom et adresse de l’expéditeur sur un domaine vérifié.	`Postline <info@example.com>`
`to`	`string[]`	Oui	Une à 100 adresses e-mail de destinataires.	`["user@example.net"]`
`subject`	`string`	Oui	Objet du message.	`Votre commande est prête`
`html`	`string`	Non	Corps HTML. html ou text est obligatoire.	`<p>…</p>`
`text`	`string`	Non	Corps en texte brut. text ou html est obligatoire.	`Commande #4821…`

Codes de réponse

Statut	HTTP	Description
`202`	Accepted	Le message est mis en file d’attente ; cela ne signifie pas encore qu’il est livré.
`400`	Bad Request	JSON invalide ou champs non pris en charge.
`401`	Unauthorized	La clé API est invalide, expirée ou révoquée.
`403`	Forbidden	Le scope manque ou le domaine de l’expéditeur n’est pas vérifié.
`422`	Unprocessable Entity	Le destinataire figure dans la liste de suppression.
`429`	Too Many Requests	La limite de requêtes du projet a été dépassée.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "recipient suppressed"
}

Envoyer un email

POST /v1/emails
Authorization: Bearer srs_live_…
Idempotency-Key: reset-4821
Content-Type: application/json

Ressources principales

POST/v1/emailsmettre un message en file d'attente

GET/v1/emails/{id}consulter l'état d'un message

POST/v1/domainsajouter un domaine d'envoi

POST/v1/domains/{id}/verifylancer les vérifications DNS

GET/POST/DELETE/v1/suppressionsgérer les destinataires supprimés

GET/POST/DELETE/v1/webhooksgérer les points de terminaison d'événements

Modèle de réponse

202 signifie mis en file d'attente, pas livré en boîte de réception. 403 peut indiquer une portée manquante ou un domaine non vérifié. 422 bloque un destinataire supprimé. 429 indique une limitation de débit.

Limites actuelles du service

L’API REST refuse les pièces jointes. Seuls les en-têtes personnalisés In-Reply-To, References, List-Unsubscribe et List-Unsubscribe-Post sont acceptés (8 au maximum). Le courrier hébergé est distinct : le client web accepte 20 pièces jointes, 25 MiB au total ; le client de bureau publié limite l’envoi à 10 MiB. HTTP 202 et email.accepted indiquent une prise en charge ; l’acceptation SMTP ne garantit ni livraison ni arrivée dans la boîte de réception.

Modèle d’accès actuel

Les clés actuelles utilisent srs_live_. Avant la vérification du domaine From, l’expéditeur sandbox partagé ne peut écrire qu’aux membres du projet. Ensuite s’appliquent quotas, suppression, limites destinataires et contrôles anti-abus. 202 signifie mis en file, pas livré.

Ressources d’intégration

Utilisez le guide pratique pour humains et agents IA ; OpenAPI fait foi pour les champs.