Comment envoyer un e-mail via l'API : PHP, Node, Python, Go

Comment envoyer un e-mail via l'API

To send an email through the YourTrend API, make a POST request to https://yourtrend.online/api/v1/messages with an Authorization: Bearer YOUR_API_KEY header and a JSON body containing from, to, subject and html. The server responds 202 Accepted, queues the message and signs it with DKIM. Below are working examples in curl and four SDKs.

Obtenez une clé API et vérifiez votre domaine

Créez une clé dans le panneau sous "Clés API" — chaque clé a des portées telles que messages:send. Vous ne pouvez envoyer que depuis une adresse sur un domaine vérifié : ajoutez le domaine, publiez SPF, DKIM et DMARC, et attendez le statut vérifié. Consultez la documentation, et vérifiez un domaine gratuitement dans le laboratoire de délivrabilité.

Démarrage rapide : curl

curl -X POST https://yourtrend.online/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Bienvenue !",
    "html": "<h1>Bonjour</h1><p>Merci de vous être inscrit.</p>",
    "stream": "transactionnel"
  }'

Une réponse réussie est HTTP 202 :

{
  "data": {
    "id": "9b1c7e2a-1f3d-4b8a-9c11-4a2f6e8d0c33",
    "status": "en attente",
    "stream": "transactionnel",
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Bienvenue !"
  }
}

PHP

Téléchargez le SDK en un seul fichier depuis /sdk/yourtrend.php — aucune dépendance, juste l'extension cURL.

<?php
require 'yourtrend.php';

$yt  = new YourTrend('YOUR_API_KEY');
$res = $yt->sendEmail(
    'noreply@yourdomain.com',
    'user@example.com',
    'Bienvenue !',
    '<h1>Bonjour</h1>'
);

if ($res['status'] === 202) {
    echo 'En attente : ' . $res['data']['data']['id'];
} else {
    echo 'Erreur : ' . ($res['data']['error']['message'] ?? 'inconnu');
}

Node.js

Le /sdk/yourtrend.js SDK utilise le fetch intégré (Node 18+) et n'a besoin d'aucun package externe.

const YourTrend = require('./yourtrend');
const yt = new YourTrend('YOUR_API_KEY');

const { status, data } = await yt.sendEmail(
  'noreply@yourdomain.com',
  'user@example.com',
  'Bienvenue !',
  '<h1>Bonjour</h1>'
);

if (status === 202) console.log('En attente :', data.data.id);
else console.error('Erreur :', data.error?.message);

Python

Le /sdk/yourtrend.py SDK est une bibliothèque standard pure (urllib) — rien à installer.

from yourtrend import YourTrend

yt = YourTrend('YOUR_API_KEY')
res = yt.send_email(
    'noreply@yourdomain.com',
    'user@example.com',
    'Bienvenue!',
    '<h1>Bonjour</h1>',
)

if res['status'] == 202:
    print('En attente:', res['data']['data']['id'])
else:
    print('Erreur:', res['data']['error']['message'])

Aller

package main

import (
    "fmt"
    "log"
    "yourtrend"
)

func main() {
    c := yourtrend.New("YOUR_API_KEY")
    resp, err := c.SendEmail(
        "noreply@yourdomain.com",
        "user@example.com",
        "Bienvenue!",
        "<h1>Bonjour</h1>",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    fmt.Println("HTTP", resp.StatusCode) // 202 = accepté
}

Champs supplémentaires

Le corps de la requête accepte plus que les quatre éléments de base :

• texte — une alternative en texte brut (recommandée avec html).
• cc, bcc, reply_to — tableaux d'adresses ou une chaîne séparée par des virgules.
• flux — transactionnel ou en masse : diviser les flux protège votre réputation IP.
• pièces jointes — un tableau d'objets {nom_fichier, contenu, type_contenu}, avec le contenu encodé en base64.
• id_modèle + variables — envoyez un modèle enregistré avec des substitutions de fusion.
• envoyer_à — un horodatage ISO-8601 pour une livraison programmée.

Idempotence et mode test

Ajoutez un Idempotency-Key : <uuid> en-tête — lors d'une nouvelle tentative de la même requête (par exemple, après un délai d'attente), YourTrend renvoie la première réponse au lieu d'envoyer un duplicata. L'en-tête X-Test-Mode : true exécute la requête sans livraison réelle et sans consommer de quota — pratique en CI.

Gestion des erreurs

Chaque erreur API arrive dans une seule enveloppe :

{
  "erreur": {
    "code": "quota_exceeded",
    "message": "Limite d'envoi quotidienne atteinte.",
    "request_id": "0f9d…"
  }
}

Vérifiez le statut HTTP, pas seulement le corps. Codes courants : 401 — clé incorrecte ; 422 — erreur de validation (un champ erreurs liste le problème par champ) ; 429 — limite de taux, réessayez avec un retour exponentiel ; 402/quota_exceeded — quota de plan épuisé. Pour les travaux en masse, utilisez POST /api/v1/messages/batch (jusqu'à 1000 messages, une réponse 207 avec un statut par message).

Vous voulez un wrapper pour votre stack ? Les SDK YourTrend pour PHP, Node, Python et Go sont chacun un fichier sans dépendance — copiez-les directement dans votre projet. La liste complète des points de terminaison et des champs se trouve dans la documentation API, et les niveaux de volume sont sur la page tarification.

Vérification du statut et des webhooks

Une fois en file d'attente, vous pouvez lire le statut d'un message avec GET /api/v1/messages/{id} — la réponse contient le statut (en file d'attente, envoyé, livré, rebondi, plaint) plus les comptes d'ouvertures et de plaintes. Interroger l'API par message est inefficace, donc configurez des webhooks pour les événements de livraison : YourTrend envoie un POST à votre URL lors de la livraison, de l'ouverture, du clic, du rebond et de la plainte. Chaque appel est signé HMAC dans un en-tête — vérifiez la signature pour rejeter les contrefaçons, et répondez 2xx dans quelques secondes ; en cas d'échec, le webhook est réessayé avec un retour croissant (une file d'attente de réessai). C'est ainsi que vous construisez une gestion robuste des échecs : les rebonds durs vont sur la liste de suppression, les plaintes reçoivent une réaction immédiate, et vos propres analyses se remplissent sans interrogation manuelle. La liste complète des types d'événements et la forme de la charge utile se trouvent dans la documentation, et les niveaux d'envoi sont sur la page tarification.