Documentation Développeur

Introduction

L'API Elymas Mailer permet d'envoyer des emails (unitaires ou en masse) depuis n'importe quelle application connectée à internet. Toutes les réponses sont en JSON. Tous les appels sont journalisés.

Authentification

Toutes les requêtes (sauf cette page) doivent inclure votre clé API dans l'en-tête HTTP Authorization.

Authorization: Bearer bns_live_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Générez une clé depuis votre tableau de bord → section "API développeur". Ne partagez jamais votre clé : elle donne accès à votre quota d'envoi.

Codes d'erreur

Quotas & limites — strictement respectés

Chaque clé API hérite des limites du compte associé :

• Le quota d'envoi journalier de votre forfait est immuable. Les emails dépassant la limite sont retournés dans le tableau skipped.
• Le rate-limit par défaut est de 60 appels/minute par clé.
• L'envoi synchrone via /send est limité à 500 destinataires par appel. Au-delà, créez une campagne (/campaigns) qui sera traitée en arrière-plan.
• L'API se ferme automatiquement à l'expiration de votre abonnement.

GET /ping — vérifie la clé

{
  "ok": true,
  "pong": true,
  "time": "2026-05-02T18:30:00+00:00",
  "user": "client@bns.test"
}

GET /account

Retourne les informations du compte, le forfait actif et la consommation du jour.

{
  "ok": true,
  "account": {
    "email": "client@bns.test",
    "plan": "Pro",
    "expires_at": "2026-06-01",
    "days_left": 28,
    "daily_used": 142,
    "daily_limit": 2000,
    "daily_remaining": 1858,
    "options": { "multi_fromname": false, "multi_subject": false, "multi_letter": false, "rotation": false }
  }
}

POST /send — envoi synchrone

Envoie un email à un ou plusieurs destinataires (jusqu'à 500) et retourne le résultat de chaque envoi.

{
  "ok": true,
  "sent": 2,
  "failed": 0,
  "skipped": [],
  "daily_used": 144,
  "daily_limit": 2000,
  "results": [
    { "to": "alice@example.com", "ok": true, "http": 200 },
    { "to": "bob@example.com",   "ok": true, "http": 200 }
  ]
}

POST /campaigns — envoi en masse asynchrone

Crée une campagne et démarre l'envoi en arrière-plan. Idéal pour des envois > 500 destinataires.

{
  "ok": true,
  "campaign_id": 42,
  "recipients": 850,
  "status": "launched",
  "status_url": "/api/v1/campaigns/42"
}

GET /campaigns

Liste les 50 dernières campagnes du compte.

GET /campaigns/{id}

Récupère le statut d'une campagne (sent_count, failed_count, status, finished_at).

Exemples — Python

import requests

API_KEY  = "bns_live_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://elymasmailer.online/api/v1"

def send_email(to, subject, html, fromname="Service Client"):
    r = requests.post(
        f"{BASE_URL}/send",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"to": to, "subject": subject, "html": html, "fromname": fromname},
        timeout=60,
    )
    r.raise_for_status()
    return r.json()

# Envoi unitaire
print(send_email("alice@example.com", "Bonjour", "<h1>Hello!</h1>"))

# Envoi en lot
print(send_email(["a@x.com", "b@x.com", "c@x.com"], "News", "<p>Notre actualité</p>"))

# Campagne en masse
def launch_campaign(emails, subject, html):
    r = requests.post(
        f"{BASE_URL}/campaigns",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"subjects": [subject], "letters": [html], "recipients": emails},
    )
    return r.json()

Exemples — PHP

<?php
$API_KEY  = 'bns_live_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$BASE_URL = 'https://elymasmailer.online/api/v1';

function bns_call(string $method, string $path, array $body = []): array {
    global $API_KEY, $BASE_URL;
    $ch = curl_init($BASE_URL . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $API_KEY,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
        CURLOPT_TIMEOUT        => 60,
    ]);
    $resp = curl_exec($ch);
    curl_close($ch);
    return json_decode($resp, true) ?: [];
}

// Compte
print_r(bns_call('GET', '/account'));

// Envoi unitaire
print_r(bns_call('POST', '/send', [
    'to'       => 'alice@example.com',
    'subject'  => 'Bonjour',
    'html'     => '<h1>Hello !</h1>',
    'fromname' => 'Mon Site',
]));

// Campagne
print_r(bns_call('POST', '/campaigns', [
    'subjects'   => ['Newsletter du mois'],
    'letters'    => ['<p>Bonjour, voici nos nouveautés...</p>'],
    'recipients' => ['a@x.com', 'b@x.com', 'c@x.com'],
]));

Exemples — JavaScript / Node.js

const API_KEY  = 'bns_live_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
const BASE_URL = 'https://elymasmailer.online/api/v1';

async function bnsCall(method, path, body) {
  const r = await fetch(BASE_URL + path, {
    method,
    headers: {
      'Authorization': 'Bearer ' + API_KEY,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  return r.json();
}

// Envoi unitaire
const res = await bnsCall('POST', '/send', {
  to: 'alice@example.com',
  subject: 'Bonjour',
  html: '<h1>Hello !</h1>',
});
console.log(res);

// Campagne
await bnsCall('POST', '/campaigns', {
  subjects: ['Promo printemps'],
  letters:  ['<p>-30% pendant 48h !</p>'],
  recipients: ['a@x.com', 'b@x.com'],
});

cURL — test rapide

# Test de la clé
curl -H "Authorization: Bearer VOTRE_CLE" https://elymasmailer.online/api/v1/ping

# Envoi d'un email
curl -X POST https://elymasmailer.online/api/v1/send \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"to":"test@example.com","subject":"Hello","html":"<h1>Test</h1>"}'