API v1 · REST · JSON

Documentation de l'API

Envoyez vos emails et vos SMS depuis votre propre application, votre boutique ou votre back-office. Une clé API suffit.

Démarrer

L'API Parino est une API REST : chaque requête est indépendante, le corps et la réponse sont au format JSON. Toutes les adresses commencent par :

Adresse de base

https://parino.tn/api/v1

Clients européens : https://parino.fr/api/v1. Les deux serveurs exposent les mêmes routes ; utilisez celui sur lequel votre compte a été créé.

Où trouver ma clé ? Connectez-vous à votre espace Parino, rubrique Clés API. Vous choisissez à la création ce que la clé a le droit de faire : envoyer des emails, des SMS, ou lire vos formulaires. La clé n'est affichée qu'une seule fois — conservez-la immédiatement.

Authentification

Chaque requête porte votre clé dans l'en-tête X-API-Key. Il n'y a ni jeton à rafraîchir, ni session à maintenir.

cURL

curl https://parino.tn/api/v1/usage \
  -H "X-API-Key: parino_live_votre_cle"

Ne mettez jamais votre clé dans du code exécuté par le navigateur. Elle serait lisible par n'importe quel visiteur, qui pourrait alors envoyer en votre nom et épuiser votre crédit. Appelez l'API depuis votre serveur.

Envoyer un email

POST/v1/emailsclé Email

Envoie un email transactionnel à un destinataire. Décompté de votre crédit email.

Champ	Type	Description
toEmail	string	Adresse du destinataire. Obligatoire.
toName	string	Nom affiché du destinataire.
subject	string	Objet de l'email. Obligatoire.
htmlContent	string	Corps en HTML.
textContent	string	Version texte, pour les clients mail qui refusent le HTML.
templateId	number	Identifiant d'un modèle de votre compte, au lieu du contenu.
params	object	Valeurs des variables du modèle.
tags	string[]	Étiquettes libres, utiles pour vos statistiques.

cURL

curl -X POST https://parino.tn/api/v1/emails \
  -H "X-API-Key: parino_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "toEmail": "client@exemple.tn",
    "toName": "Sonia Ben Ali",
    "subject": "Votre commande est prête",
    "htmlContent": "<p>Bonjour Sonia, votre commande vous attend.</p>",
    "tags": ["commande"]
  }'

Réponse 200

{
  "id": 4821,
  "toEmail": "client@exemple.tn",
  "subject": "Votre commande est prête",
  "status": "SENT",
  "sentAt": "2026-08-14T09:12:44Z"
}

Envoyer un SMS

POST/v1/smsclé SMS

Envoie un SMS. Décompté de votre crédit SMS.

Champ	Type	Description
recipient	string	Numéro au format international, ex. +21620123456. Obligatoire.
senderName	string	Nom affiché sur le téléphone, 15 caractères maximum. Obligatoire.
content	string	Texte du message, 1000 caractères maximum. Obligatoire.

cURL

curl -X POST https://parino.tn/api/v1/sms \
  -H "X-API-Key: parino_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+21620123456",
    "senderName": "MaSociete",
    "content": "Votre commande est prete. Merci !"
  }'

Attention aux accents. Un SMS sans accent contient 160 caractères ; dès qu'un accent ou un emoji apparaît, la limite tombe à 70 et le message est facturé en plusieurs SMS.

Créer ou mettre à jour un contact

POST/v1/contacts

Enregistre un contact. L'opération est idempotente : réenvoyer la même adresse met le contact à jour au lieu d'en créer un second.

Champ	Type	Description
email	string	Adresse du contact. Obligatoire, sert de clé.
firstName / lastName	string	Prénom et nom.
phone	string	Numéro de téléphone.
company	string	Société.
country / city	string	Pays et ville.
birthDate	date	Date de naissance, format AAAA-MM-JJ.
source	string	Origine du contact, ex. « Site web ». Utile pour vos statistiques.
listIds	number[]	Listes auxquelles rattacher le contact.

JavaScript (Node.js)

const res = await fetch('https://parino.tn/api/v1/contacts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.PARINO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'client@exemple.tn',
    firstName: 'Sonia',
    source: 'Site web',
    listIds: [3],
  }),
});
const contact = await res.json();

Lister vos listes de contacts

GET/v1/lists

Renvoie vos listes avec leur identifiant, à utiliser dans listIds.

Réponse 200

[
  { "id": 3, "name": "Newsletter", "contactsCount": 1248 },
  { "id": 7, "name": "Clients 2026", "contactsCount": 312 }
]

Connaître votre crédit restant

GET/v1/usage

Renvoie votre forfait et le crédit restant sur chaque canal.

Réponse 200

{
  "plan": "BUSINESS",
  "email": { "used": 4813, "limit": 15000, "remaining": 10187, "unlimited": false },
  "sms":   { "used": 180,  "limit": 500,   "remaining": 320,   "unlimited": false },
  "periodStart": "2026-08-01T00:00:00Z",
  "periodEnd":   "2026-09-01T00:00:00Z"
}

Forfaits illimités. limit et remaining valent alors -1, et unlimited passe à true. Testez unlimited avant d'afficher le nombre, sous peine d'annoncer « -1 email restant » à vos utilisateurs.

Suivre vos quotas sans requête supplémentaire

Chaque envoi renvoie votre solde dans les en-têtes de la réponse. Vous n'avez donc pas besoin d'appeler /v1/usage après chaque message : le solde tient déjà compte de l'envoi qui vient d'être effectué.

En-têtes de réponse

X-Parino-Email-Remaining: 10186
X-Parino-Email-Limit: 15000

X-Parino-Sms-Remaining: 319
X-Parino-Sms-Limit: 500

Surveillez ces valeurs pour prévenir vos équipes avant l'épuisement du crédit. Une fois le quota atteint, les envois sont refusés avec un code 402 jusqu'au mois suivant ou au changement de forfait.

Codes d'erreur

Une erreur renvoie toujours le même format, avec un message lisible et, pour les erreurs de validation, le détail champ par champ.

Réponse d'erreur

{
  "status": 400,
  "error": "Validation Failed",
  "message": "Données invalides",
  "path": "/api/v1/emails",
  "timestamp": "2026-08-14T09:12:44Z",
  "details": ["subject: ne doit pas être vide"]
}

Code	Signification	Que faire
400	Requête invalide	Lisez details : il indique le champ fautif.
401	Clé absente ou invalide	Vérifiez l'en-tête X-API-Key.
403	Portée insuffisante	La clé n’autorise pas cette opération. Créez-en une avec la bonne portée.
402	Crédit épuisé	Attendez le mois suivant ou changez de forfait.
404	Ressource introuvable	Vérifiez l'identifiant transmis.
502	Service d’envoi indisponible	Incident temporaire : réessayez dans quelques instants.

Rejouer un envoi après une erreur 502 ? Le message a pu partir malgré l'erreur. Sur un email de confirmation, un doublon est sans gravité ; sur un code à usage unique, vérifiez d'abord avec /v1/usage si le crédit a été décompté.

Prêt à connecter votre application ?

Créez votre compte, générez une clé et envoyez votre premier message en quelques minutes.

Créer un compte Poser une question