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

Envoyez une clé srs_live_ à portée limitée émise par le tableau de bord comme jeton Bearer. Chaque clé a ses propres scopes (emails:send, webhooks:write …) ; les clés révoquées ou expirées sont rejetées avec 401.

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	Adresses des destinataires ; to + cc + bcc ne doivent pas dépasser 100 au total.	`["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…`
`cc / bcc`	`string[]`	Non	Copie et copie cachée (comptées dans la limite de 100).	`["team@example.com"]`
`reply_to`	`string[]`	Non	Jusqu’à 10 adresses de réponse.	`["support@example.com"]`
`send_at`	`string · date-time`	Non	Envoi programmé jusqu’à 30 jours (RFC 3339).	`2026-11-06T09:00:00Z`
`tags`	`object`	Non	Jusqu’à 20 tags clé/valeur.	`{"type":"receipt"}`
`headers`	`object`	Non	Jusqu’à 8 : In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post.	`{"References":"<…>"}`
`template / variables`	`string / object`	Non	ID de modèle publié ; objet et corps issus des variables.	`"order-ready"`

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/emailsmet un message en file d’attente

POST/v1/emails/batchjusqu’à 100 messages par requête

GET/v1/emailsliste les messages récents

GET/v1/emails/{id}état d’un message

DELETE/v1/emails/{id}/scheduleannule un envoi programmé

GET/POST/v1/domainsliste ou ajoute des domaines d’envoi

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

POST/v1/suppressionssupprime un destinataire

GET/DELETE/v1/suppressions/{email}consulte ou retire une suppression

GET/POST/v1/webhooksliste ou crée des endpoints webhook

DELETE/v1/webhooks/{id}supprime un endpoint

GET/v1/webhooks/{id}/deliveriesjournal des tentatives de livraison

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replayrejoue une livraison

GET/POST/v1/templatesliste ou crée des modèles

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.