Emails

2 endpoints

get/v1/emails/conversations

Lister les conversations email

Retourne la liste paginée des threads email du client (cursor v2). Tri stable last_message_at DESC, id DESC — les conversations avec un échange récent en premier. last_message_at est NOT NULL côté table.

Lecture seule

L'API publique expose seulement la liste des threads. Le détail des messages individuels d'une conversation n'est pas encore exposé via l'API publique — le payload se limite aux métadonnées du thread. Pour envoyer un email, utiliser POST /v1/emails/send.

Required scopes: email:read

Responses

Status	Description
`200`	Liste paginée des conversations email.
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Example request

curl -X GET 'https://app.capturia.io/api/v1/emails/conversations' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

post/v1/emails/send

Envoyer un email transactionnel

Met en queue un email transactionnel pour livraison via Resend. L'email est créé avec status="queued", priority=1, type="transactional" et délivré de manière asynchrone par le worker email — la réponse 201 confirme la mise en queue, pas la délivrance finale.

Expéditeur résolu serveur-side

L'expéditeur (from) est dérivé du sender par défaut du client (client_email_senders.is_default = true). Si aucun sender par défaut n'est configuré, la requête retourne 400 no_sender_configured.

Idempotency

Le header Idempotency-Key n'est PAS supporté sur cette route — un retry naïf créera un second envoi. Une clé d'idempotence interne est générée serveur-side (api-transactional/{clientId}/{ts}) pour protéger uniquement contre les doubles inserts en base.

Mode test

"test": true dans le body permet de valider une intégration sans viser un vrai contact : les variables de personnalisation sont interpolées avec des valeurs d'exemple, le sujet est préfixé [TEST], et les vérifications de conformité destinataire sont contournées. En contrepartie, le destinataire doit être un membre actif de l'équipe du client (sinon 400 recipient_not_allowed) et un quota de 50 tests / 24 h glissantes s'applique, partagé avec les boutons de test de la plateforme (sinon 429 test_quota_exceeded).

Required scopes: email:send

Request body

#/components/schemas/EmailSendPayload

Responses

Status	Description
`201`	Email mis en queue.
`400`	Validation des paramètres ou du body a échoué.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`415`	Le header `Content-Type` est manquant ou non supporté pour cet endpoint.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Example request

curl -X POST 'https://app.capturia.io/api/v1/emails/send' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "[email protected]",
  "subject": "Confirmation de votre commande",
  "body": "<p>Bonjour Alex,</p><p>Votre commande est confirmée.</p>"
}'