Documentation développeur

API email, domaines et boîtes prête pour vos apps.

Cette documentation montre comment créer des adresses, générer en masse, connecter un domaine, gérer DNS/nameservers, lire une boîte, récupérer un code OTP et envoyer des emails. Chaque appel agit comme un compte client normal et respecte automatiquement le plan, les quotas et la sécurité.

Copier le starter Voir les règles sécurité

curl -X POST https://luxalias.com/api/aliases \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"robot-test","domain":"luxalias.com","goto":"[email protected]"}'

# Reponse
{
  "id": 123,
  "address": "[email protected]",
  "goto": "[email protected]",
  "is_active": true
}

Authentification

Authorization: Bearer alk_... ou X-API-Key: alk_...

Plans

Toutes les limites sont appliquees cote serveur selon le plan actif.

Securite

Cles hachees en base, quotas par compte/cle, reponses 429 avec Retry-After.

Démarrage rapide

Utilisez cette séquence pour brancher LuxMail dans votre infrastructure. Les exemples sont pensés pour être collés directement dans un backend, un worker ou un script sécurisé.

Créer un compte ou se connecter, puis générer une clé API dans Paramètres > Clés API.

Mettre la clé dans un secret serveur: .env, Docker secret, Vercel Environment Variable, GitHub Actions Secret, etc.

Appeler l’API depuis votre backend, jamais directement depuis un navigateur public.

Lire /apikeys/capabilities avant les grosses opérations pour connaître le plan, les limites et les fonctionnalités actives.

Gérer proprement les erreurs 401, 403, 422 et 429 avec retry/backoff quand nécessaire.

Authentification et installation

envVariables d'environnement

# .env - ne jamais commiter ce fichier
LUXALIAS_API_BASE=https://luxalias.com/api
LUXALIAS_API_KEY=alk_votre_cle_api

bashCréer compte, login, créer clé

# 1. Creer un compte client/API
curl -X POST https://luxalias.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Robot Production","email":"[email protected]","password":"MotDePasseLongEtUnique!2026"}'

# 2. Se connecter pour obtenir un JWT temporaire
curl -X POST https://luxalias.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"MotDePasseLongEtUnique!2026"}'

# 3. Creer une cle API persistante avec le JWT recu
curl -X POST https://luxalias.com/api/apikeys \
  -H "Authorization: Bearer JWT_RECU_AU_LOGIN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Serveur production","expires_in_days":365}'

Starter complet prêt à coller

Placez ce client dans votre backend, par exemple `lib/luxalias.js`. Ensuite appelez-le depuis vos routes serveur, tâches cron, workers ou scripts internes.

jsClient Node.js

// lib/luxalias.js - a mettre cote serveur: Node.js, Express, Next.js API route, worker
const API_BASE = process.env.LUXALIAS_API_BASE || 'https://luxalias.com/api';
const API_KEY = process.env.LUXALIAS_API_KEY;

if (!API_KEY) throw new Error('LUXALIAS_API_KEY manquant dans .env');

async function lux(path, options = {}) {
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...(options.headers || {}),
    },
  });

  const data = await res.json().catch(() => ({}));
  if (!res.ok) {
    const err = new Error(data.message || `LuxMail API error ${res.status}`);
    err.status = res.status;
    err.data = data;
    throw err;
  }
  return data;
}

module.exports = {
  capabilities: () => lux('/apikeys/capabilities'),
  createAlias: ({ local_part, domain, goto, description }) => lux('/aliases', {
    method: 'POST',
    body: JSON.stringify({ local_part, domain, goto, description }),
  }),
  bulkAliases: ({ count, domain, goto, description }) => lux('/aliases/bulk', {
    method: 'POST',
    body: JSON.stringify({ count, domain, goto, description }),
  }),
  latestCode: (aliasId, digits = 6) => lux(`/mailboxes/${aliasId}/latest-code?digits=${digits}&limit=30`),
  sendMail: (payload) => lux('/mail/send', { method: 'POST', body: JSON.stringify(payload) }),
};

jsUtilisation Node.js

// scripts/demo-luxalias.js
require('dotenv').config();
const lux = require('../lib/luxalias');

async function main() {
  const caps = await lux.capabilities();
  console.log('Plan:', caps.plan.name, caps.limits.aliases);

  const alias = await lux.createAlias({
    local_part: 'robot-test',
    domain: 'luxalias.com',
    goto: '[email protected]',
    description: 'Alias cree par API',
  });

  console.log('Alias cree:', alias.address, 'id:', alias.id);
  const code = await lux.latestCode(alias.id, 6);
  console.log('Dernier code:', code.code);
}

main().catch((err) => {
  console.error('Erreur:', err.status, err.data || err.message);
  process.exit(1);
});

pyClient Python

# luxalias_client.py
import os
import requests

API_BASE = os.getenv('LUXALIAS_API_BASE', 'https://luxalias.com/api')
API_KEY = os.environ['LUXALIAS_API_KEY']

def lux(method, path, json=None):
    response = requests.request(
        method,
        f"{API_BASE}{path}",
        headers={'Authorization': f'Bearer {API_KEY}'},
        json=json,
        timeout=30,
    )
    data = response.json() if response.content else {}
    if response.status_code >= 400:
        raise RuntimeError(f'LuxMail {response.status_code}: {data}')
    return data

alias = lux("POST", "/aliases", {
    'local_part': 'robot-test',
    'domain': 'luxalias.com',
    'goto': '[email protected]',
})
print('Alias:', alias['address'])
code = lux("GET", f"/mailboxes/{alias['id']}/latest-code?digits=6&limit=30")
print('Dernier code:', code.get('code'))

jsProxy Next.js sécurisé

// pages/api/create-luxalias-email.js - exemple Next.js securise
export default async function handler(req, res) {
  if (req.method !== 'POST') return res.status(405).json({ message: 'Method not allowed' });

  const response = await fetch(`${process.env.LUXALIAS_API_BASE}/aliases`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LUXALIAS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      local_part: req.body.local_part,
      domain: req.body.domain || 'luxalias.com',
      goto: req.body.goto,
    }),
  });

  const data = await response.json();
  return res.status(response.status).json(data);
}

Fonctions disponibles

Adresses email

GET/aliases

Lister les adresses du compte.

POST/aliases

Créer une adresse unique.

POST/aliases/bulk

Créer plusieurs adresses selon le plan.

PUT/aliases/:id

Modifier description, expiration ou statut.

DELETE/aliases/:id

Supprimer une adresse et la réserver.

Domaines et DNS

POST/domains

Connecter un domaine externe à vérifier.

POST/domains/:id/verify

Valider le TXT de propriété.

POST/domains/:id/check-records

Contrôler A, MX, SPF, DKIM, DMARC.

GET/domain-shop/dns/:domain

Lire la zone DNS d’un domaine acheté.

POST/domain-shop/dns/:domain/nameservers

Changer les nameservers.

Boîtes et robots

GET/mailboxes/:id/messages

Lire les messages avec pagination.

GET/mailboxes/:id/messages/:uid

Lire un message complet.

GET/mailboxes/:id/latest-code

Extraire un code OTP reçu.

POST/mail/send

Envoyer depuis une adresse autorisée.

Exemples par fonctionnalité

bashCapacités, plan et limites

curl https://luxalias.com/api/apikeys/capabilities \
  -H "Authorization: Bearer alk_votre_cle_api"

bashCréer, modifier, supprimer des adresses

# Creer une adresse
curl -X POST https://luxalias.com/api/aliases \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"client-42","domain":"luxalias.com","goto":"[email protected]","description":"Inscription client 42"}'

# Lister les adresses
curl https://luxalias.com/api/aliases \
  -H "Authorization: Bearer alk_votre_cle_api"

# Mettre en pause une adresse
curl -X PUT https://luxalias.com/api/aliases/ALIAS_ID \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"is_active":false,"description":"Desactive depuis mon CRM"}'

# Supprimer une adresse
curl -X DELETE https://luxalias.com/api/aliases/ALIAS_ID \
  -H "Authorization: Bearer alk_votre_cle_api"

bashGénération en masse

curl -X POST https://luxalias.com/api/aliases/bulk \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"count":100,"domain":"luxalias.com","goto":"[email protected]","description":"Campagne test autorisee"}'

bashConnecter un domaine externe

# Ajouter un domaine externe a verifier
curl -X POST https://luxalias.com/api/domains \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"domain":"exemple.com","default_recipient":"[email protected]"}'

# Verifier la propriete TXT
curl -X POST https://luxalias.com/api/domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer alk_votre_cle_api"

# Verifier A, MX, SPF, DKIM et DMARC
curl -X POST https://luxalias.com/api/domains/DOMAIN_ID/check-records \
  -H "Authorization: Bearer alk_votre_cle_api"

bashDNS complet d'un domaine acheté

# Lire les DNS d’un domaine achete chez LuxMail
curl https://luxalias.com/api/domain-shop/dns/exemple.com \
  -H "Authorization: Bearer alk_votre_cle_api"

# Ajouter un A record
curl -X POST https://luxalias.com/api/domain-shop/dns/exemple.com/records \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"@","value":"203.0.113.10","ttl":3600}'

# Ajouter un MX record
curl -X POST https://luxalias.com/api/domain-shop/dns/exemple.com/records \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"type":"MX","host":"@","value":"mail.exemple.com","distance":10,"ttl":3600}'

# Modifier un record
curl -X PUT https://luxalias.com/api/domain-shop/dns/exemple.com/records/RECORD_ID \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"host":"www","value":"exemple.com","ttl":1800}'

# Supprimer un record
curl -X DELETE https://luxalias.com/api/domain-shop/dns/exemple.com/records/RECORD_ID \
  -H "Authorization: Bearer alk_votre_cle_api"

bashNameservers Cloudflare, lock et unlock

# Pointer le domaine vers Cloudflare ou un autre fournisseur DNS
curl -X POST https://luxalias.com/api/domain-shop/dns/exemple.com/nameservers \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"nameservers":["coraline.ns.cloudflare.com","ignat.ns.cloudflare.com"]}'

# Verrouiller le domaine contre un transfert non desire
curl -X POST https://luxalias.com/api/domain-shop/domains/exemple.com/lock \
  -H "Authorization: Bearer alk_votre_cle_api"

# Deverrouiller uniquement avant un transfert volontaire
curl -X POST https://luxalias.com/api/domain-shop/domains/exemple.com/unlock \
  -H "Authorization: Bearer alk_votre_cle_api"

bashLire la boîte et récupérer un code

# Lire les derniers messages d’une adresse
curl "https://luxalias.com/api/mailboxes/ALIAS_ID/messages?limit=20&page=1" \
  -H "Authorization: Bearer alk_votre_cle_api"

# Lire le contenu complet d’un message
curl https://luxalias.com/api/mailboxes/ALIAS_ID/messages/MESSAGE_UID \
  -H "Authorization: Bearer alk_votre_cle_api"

# Recuperer automatiquement le dernier code OTP
curl "https://luxalias.com/api/mailboxes/ALIAS_ID/latest-code?digits=6&limit=30" \
  -H "Authorization: Bearer alk_votre_cle_api"

bashEnvoyer un email

curl -X POST https://luxalias.com/api/mail/send \
  -H "Authorization: Bearer alk_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"from_alias":"[email protected]","to":"[email protected]","subject":"Bienvenue","html":"<h1>Bonjour</h1><p>Votre compte est pret.</p>"}'

Sécurité, limites et anti-abus

Une clé API donne presque les mêmes droits qu’un compte client. Elle ne doit jamais être placée dans du JavaScript public, une app mobile décompilable, un dépôt Git ou une extension non contrôlée. Utilisez toujours un backend/proxy qui garde la clé côté serveur.

Quotas impossibles à contourner

Les créations d’adresses, domaines, bulk et envois relisent le plan actif côté serveur. Si le plan gratuit ou expiré ne permet pas une action, l’API répond 403 upgrade_required.

Rate-limit par compte et clé

En plus du rate-limit IP, l’API applique une fenêtre par utilisateur/clé. Les robots reçoivent 429 API_RATE_LIMITED avec Retry-After pour attendre proprement.

Révocation immédiate

Supprimez une clé depuis Paramètres > Clés API si vous pensez qu’elle a fuité. Les clés sont hachées en base et le token complet n’est affiché qu’une seule fois.

Usage responsable

Automatisez vos workflows légitimes: tests, onboarding, CRM, notifications et boîtes de réception internes. N’utilisez pas l’API pour contourner des protections de plateformes tierces ou envoyer du spam.

Codes d’erreur à gérer

401HTTP 401

Token manquant, invalide ou expiré. Reconnectez-vous ou régénérez une clé.

403HTTP 403

Plan insuffisant, domaine non autorisé, compte suspendu ou quota atteint.

409HTTP 409

Adresse déjà utilisée ou domaine déjà ajouté.

422HTTP 422

Données invalides: email, domaine, DNS ou payload incomplet.

429HTTP 429

Trop de requêtes. Respectez Retry-After avant de relancer.

500/502HTTP 500/502

Erreur serveur ou connecteur externe temporaire. Réessayez avec backoff.