Documentation API Mailstride v1

API RESTful complète pour automatiser vos campagnes d'emailing et gérer vos contacts

Démarrage rapide

1. Créez une clé API

Générez votre clé API depuis votre dashboard

Accéder au dashboard →

2. Faites votre première requête

Utilisez votre clé pour accéder à l'API

3. Automatisez

Intégrez Mailstride dans vos workflows

Exemple de requête

curl -X GET "https://mailstride.netlify.app/api/v1/campaigns" \
  -H "Authorization: Bearer ms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentification

L'API Mailstride utilise des clés API pour l'authentification. Vous devez inclure votre clé API dans l'en-tête Authorization de chaque requête.

Important : Ne partagez jamais votre clé API publiquement. Conservez-la en sécurité comme un mot de passe.

Format d'authentification :

Authorization: Bearer ms_live_YOUR_API_KEY

Limites de taux (Rate Limiting)

Chaque clé API a des limites de taux configurables. Par défaut :

1000 requêtes par heure
10 000 requêtes par jour

Chaque réponse inclut des en-têtes indiquant votre usage actuel :

X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 999
X-RateLimit-Reset-Hour: 1699876543
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9999
X-RateLimit-Reset-Day: 1699962943

Si vous dépassez votre limite, vous recevrez une réponse 429 Too Many Requests.

Endpoints disponibles

Campagnes

GET/api/v1/campaigns

Liste toutes vos campagnes

Permission requise :

campaigns:read

Paramètres (query) :

page - Numéro de page (défaut: 1)
limit - Résultats par page (défaut: 50, max: 100)
status - Filtrer par statut (draft, scheduled, sending, sent, completed)

Exemple de requête :

curl -X GET "https://mailstride.netlify.app/api/v1/campaigns?page=1&limit=10" \
  -H "Authorization: Bearer ms_live_YOUR_API_KEY"

Réponse (200 OK) :

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Newsletter Janvier",
      "subject": "Nouveautés 2025",
      "status": "sent",
      "stats": {
        "sent": 1000,
        "opened": 450,
        "clicked": 120
      },
      "createdAt": "2025-01-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "pages": 3
  }
}

POST/api/v1/campaigns

Créer une nouvelle campagne

Permission requise :

campaigns:write

Corps de la requête :

{
  "name": "Newsletter Février",
  "subject": "Offres spéciales",
  "content": "<html>...</html>",
  "recipients": ["contact1@example.com", "contact2@example.com"],
  "scheduledFor": "2025-02-01T09:00:00Z" // Optionnel
}

Exemple de requête :

curl -X POST "https://mailstride.netlify.app/api/v1/campaigns" \
  -H "Authorization: Bearer ms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Février",
    "subject": "Offres spéciales",
    "content": "<html>...</html>"
  }'

Réponse (201 Created) :

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Newsletter Février",
    "subject": "Offres spéciales",
    "status": "draft",
    "createdAt": "2025-01-15T14:30:00Z"
  },
  "message": "Campaign created successfully"
}

Contacts

GET/api/v1/contacts

Liste tous vos contacts

Permission requise :

contacts:read

Paramètres (query) :

page - Numéro de page
limit - Résultats par page
status - Filtrer par statut (active, unsubscribed, bounced)
tag - Filtrer par tag
search - Recherche (email, nom, entreprise)

Exemple de requête :

curl -X GET "https://mailstride.netlify.app/api/v1/contacts?search=john" \
  -H "Authorization: Bearer ms_live_YOUR_API_KEY"

POST/api/v1/contacts

Créer un nouveau contact

Permission requise :

contacts:write

Corps de la requête :

{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "company": "Acme Inc",
  "position": "CEO",
  "phone": "+33612345678",
  "country": "France",
  "tags": ["lead", "vip"],
  "customFields": {
    "industry": "Tech",
    "revenue": "1M+"
  }
}

Exemple de requête :

curl -X POST "https://mailstride.netlify.app/api/v1/contacts" \
  -H "Authorization: Bearer ms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }'

Codes d'erreur

Code	Description
200	Requête réussie
201	Ressource créée avec succès
400	Requête invalide (paramètres manquants ou incorrects)
401	Non authentifié (clé API manquante ou invalide)
403	Permission refusée (clé API sans permission requise)
404	Ressource non trouvée
409	Conflit (ressource existe déjà)
429	Limite de taux dépassée
500	Erreur serveur interne

Besoin d'aide ?

Notre équipe est là pour vous aider à intégrer l'API Mailstride dans vos projets.