Sigmabox API Documentation

Demarrage rapide

URL de base

Toutes les requetes doivent etre envoyees a l'URL de base suivante :

https://api.sigmabox.fr

Authentification

Authentifiez vos requetes en incluant votre cle API dans l'en-tete HTTP. Deux methodes sont supportees :

# Methode 1 — En-tete X-API-Key (recommande)
curl -H "X-API-Key: sk_live_xxx" https://api.sigmabox.fr/me

# Methode 2 — En-tete Authorization Bearer
curl -H "Authorization: Bearer sk_live_xxx" https://api.sigmabox.fr/me

Vous n'avez pas encore de cle API ? Creez-en une gratuitement depuis votre tableau de bord Sigmabox.

Format de reponse

Toutes les reponses sont en JSON et suivent un format standardise. Les reponses reussies contiennent {"success": true, "data": {...}}. Les erreurs contiennent {"success": false, "error": "..."}.

Succes

{
  "success": true,
  "data": {
    "id": "xxx",
    "...": "..."
  }
}

Erreur

{
  "success": false,
  "error": "Cle API invalide ou manquante."
}

Limites de debit

Les limites suivantes s'appliquent pour proteger l'infrastructure :

Limite	Valeur
Par adresse IP	60 requetes / minute
Par cle API	300 requetes / minute

En cas de depassement, l'API retourne un code HTTP 429 avec le corps {"success": false, "error": "Trop de requetes. Veuillez reessayer plus tard."} et les en-tetes suivants : Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Scopes (permissions)

Chaque cle API possede un ou plusieurs scopes qui determinent les actions autorisees :

Scope	Description
READ	Lecture des donnees (signatures, campagnes, analytics, etc.)
WRITE	Creation, modification et suppression de ressources
ADMIN	Gestion des organisations, transferts et parametres avances

Profil

GET

/me

READ

Retourne les informations du profil associe a la cle API utilisee.

Exemple curl

curl -X GET https://api.sigmabox.fr/me \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Jean Dupont",
    "company": "Entreprise SAS",
    "isPremium": true,
    "plan": "business",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Signatures

GET

/signatures

READ

Liste toutes les signatures de votre compte.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)

Exemple curl

curl -X GET "https://api.sigmabox.fr/signatures?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "signatures": [
      {
        "id": "sig_abc123",
        "name": "Signature principale",
        "isActive": true,
        "isBlurred": false,
        "createdAt": "2025-02-01T08:00:00.000Z",
        "updatedAt": "2025-03-10T14:22:00.000Z"
      },
      {
        "id": "sig_def456",
        "name": "Signature marketing",
        "isActive": false,
        "isBlurred": false,
        "createdAt": "2025-02-15T09:30:00.000Z",
        "updatedAt": "2025-03-12T11:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

GET

/signatures/:id

READ

Retourne le detail d'une signature specifique.

Exemple curl

curl -X GET https://api.sigmabox.fr/signatures/sig_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "sig_abc123",
    "name": "Signature principale",
    "isActive": true,
    "isBlurred": false,
    "html": "<table>...</table>",
    "campaigns": [
      "cmp_xyz789"
    ],
    "createdAt": "2025-02-01T08:00:00.000Z",
    "updatedAt": "2025-03-10T14:22:00.000Z"
  }
}

PATCH

/signatures/:id

WRITE

Met a jour les proprietes d'une signature.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Non	Nouveau nom de la signature
`isActive`	boolean	Non	Activer ou desactiver la signature
`isBlurred`	boolean	Non	Flouter ou non la signature

Exemple curl

curl -X PATCH https://api.sigmabox.fr/signatures/sig_abc123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Signature mise a jour", "isActive": true}'

Reponse

{
  "success": true,
  "data": {
    "id": "sig_abc123",
    "name": "Signature mise a jour",
    "isActive": true,
    "isBlurred": false,
    "updatedAt": "2025-03-21T09:15:00.000Z"
  }
}

DELETE

/signatures/:id

WRITE

Supprime definitivement une signature.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/signatures/sig_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Signature supprimee avec succes."
  }
}

POST

/signatures/:id/toggle-active

WRITE

Bascule l'etat actif/inactif d'une signature. Pratique pour activer ou desactiver rapidement.

Exemple curl

curl -X POST https://api.sigmabox.fr/signatures/sig_abc123/toggle-active \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "sig_abc123",
    "isActive": false,
    "message": "Signature desactivee."
  }
}

GET

/signatures/:id/download

READ

Telecharge le fichier HTML de la signature. Le contenu est retourne directement en text/html.

Exemple curl

curl -X GET https://api.sigmabox.fr/signatures/sig_abc123/download \
  -H "X-API-Key: YOUR_API_KEY" \
  -o signature.html

Reponse

<!-- Le fichier HTML de la signature est telecharge directement -->
<table style="font-family: Arial, sans-serif;">
  <tr>
    <td>
      <strong>Jean Dupont</strong><br/>
      Directeur Commercial — Entreprise SAS
    </td>
  </tr>
</table>

Campagnes

GET

/campaigns

READ

Liste toutes les campagnes avec filtrage et pagination.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)
`search`	string	Non	Recherche par nom de campagne
`isActive`	boolean	Non	Filtrer par etat actif/inactif
`signatureId`	string	Non	Filtrer par identifiant de signature

Exemple curl

curl -X GET "https://api.sigmabox.fr/campaigns?page=1&limit=10&isActive=true" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "cmp_xyz789",
        "name": "Promo Ete 2025",
        "isActive": true,
        "signatureId": "sig_abc123",
        "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
        "targetUrl": "https://entreprise.fr/promo",
        "clicks": 342,
        "impressions": 8920,
        "createdAt": "2025-06-01T07:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1
    }
  }
}

POST

/campaigns

WRITE

Cree une nouvelle campagne de banniere.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Oui	Nom de la campagne
`signatureId`	string	Oui	Identifiant de la signature associee
`bannerUrl`	string	Oui	URL de l'image de la banniere
`targetUrl`	string	Oui	URL de destination au clic
`isActive`	boolean	Non	Activer immediatement (defaut : true)

Exemple curl

curl -X POST https://api.sigmabox.fr/campaigns \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promo Ete 2025",
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/promo",
    "isActive": true
  }'

Reponse

{
  "success": true,
  "data": {
    "id": "cmp_xyz789",
    "name": "Promo Ete 2025",
    "isActive": true,
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/promo",
    "clicks": 0,
    "impressions": 0,
    "createdAt": "2025-06-01T07:00:00.000Z"
  }
}

GET

/campaigns/:id

READ

Retourne le detail d'une campagne specifique.

Exemple curl

curl -X GET https://api.sigmabox.fr/campaigns/cmp_xyz789 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "cmp_xyz789",
    "name": "Promo Ete 2025",
    "isActive": true,
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/promo",
    "clicks": 342,
    "impressions": 8920,
    "ctr": 3.83,
    "createdAt": "2025-06-01T07:00:00.000Z",
    "updatedAt": "2025-06-15T10:00:00.000Z"
  }
}

PATCH

/campaigns/:id

WRITE

Met a jour une campagne existante.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Non	Nouveau nom
`bannerUrl`	string	Non	Nouvelle URL de banniere
`targetUrl`	string	Non	Nouvelle URL de destination
`isActive`	boolean	Non	Activer ou desactiver

Exemple curl

curl -X PATCH https://api.sigmabox.fr/campaigns/cmp_xyz789 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Promo Automne 2025", "targetUrl": "https://entreprise.fr/automne"}'

Reponse

{
  "success": true,
  "data": {
    "id": "cmp_xyz789",
    "name": "Promo Automne 2025",
    "isActive": true,
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/automne",
    "updatedAt": "2025-09-01T08:00:00.000Z"
  }
}

DELETE

/campaigns/:id

WRITE

Supprime definitivement une campagne.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/campaigns/cmp_xyz789 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Campagne supprimee avec succes."
  }
}

GET

/campaigns/:id/analytics

READ

Retourne les statistiques detaillees d'une campagne sur une periode donnee.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 90)

Exemple curl

curl -X GET "https://api.sigmabox.fr/campaigns/cmp_xyz789/analytics?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "campaignId": "cmp_xyz789",
    "period": {
      "from": "2025-05-22",
      "to": "2025-06-21"
    },
    "totals": {
      "clicks": 342,
      "impressions": 8920,
      "ctr": 3.83
    },
    "daily": [
      {
        "date": "2025-06-21",
        "clicks": 18,
        "impressions": 310,
        "ctr": 5.81
      },
      {
        "date": "2025-06-20",
        "clicks": 12,
        "impressions": 295,
        "ctr": 4.07
      }
    ]
  }
}

GET

/campaigns/export

READ

Exporte les donnees des campagnes au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30)
`campaignIds`	string	Non	IDs de campagnes separes par virgules
`signatureIds`	string	Non	IDs de signatures separes par virgules

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/campaigns/export?days=30" \
  -o campaigns.csv

Reponse

Date,Campagne,Signature,Clics,Impressions,CTR
2025-03-21,Promo Ete 2025,Signature principale,18,310,5.81
2025-03-20,Promo Ete 2025,Signature principale,12,295,4.07

Validation Email

POST

/email-validation/validate

WRITE

Valide une adresse email en temps reel. Consomme 1 credit par verification.

Corps de la requete

Parametre	Type	Requis	Description
`email`	string	Oui	Adresse email a verifier

Exemple curl

curl -X POST https://api.sigmabox.fr/email-validation/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Reponse

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "isValid": true,
    "status": "deliverable",
    "score": 98,
    "checks": {
      "syntax": true,
      "mxRecords": true,
      "disposable": false,
      "roleAccount": false,
      "freeProvider": false
    },
    "provider": "OVH",
    "verifiedAt": "2025-03-21T10:00:00.000Z"
  }
}

GET

/email-validation/history

READ

Retourne l'historique de vos validations email unitaires.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)

Exemple curl

curl -X GET "https://api.sigmabox.fr/email-validation/history?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "validations": [
      {
        "email": "[email protected]",
        "isValid": true,
        "status": "deliverable",
        "score": 98,
        "verifiedAt": "2025-03-21T10:00:00.000Z"
      },
      {
        "email": "[email protected]",
        "isValid": false,
        "status": "disposable",
        "score": 5,
        "verifiedAt": "2025-03-21T09:55:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 54,
      "totalPages": 6
    }
  }
}

GET

/email-validation/bulk

READ

Liste tous les traitements de validation en masse (bulk).

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20)

Exemple curl

curl -X GET "https://api.sigmabox.fr/email-validation/bulk?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "bulkJobs": [
      {
        "id": "bulk_001",
        "fileName": "contacts_mars.csv",
        "totalEmails": 1500,
        "processed": 1500,
        "valid": 1320,
        "invalid": 180,
        "status": "completed",
        "createdAt": "2025-03-15T14:00:00.000Z",
        "completedAt": "2025-03-15T14:12:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 3,
      "totalPages": 1
    }
  }
}

GET

/email-validation/bulk/:id

READ

Retourne le detail et les resultats d'un traitement bulk specifique.

Exemple curl

curl -X GET https://api.sigmabox.fr/email-validation/bulk/bulk_001 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "bulk_001",
    "fileName": "contacts_mars.csv",
    "totalEmails": 1500,
    "processed": 1500,
    "valid": 1320,
    "invalid": 180,
    "status": "completed",
    "results": [
      {
        "email": "[email protected]",
        "isValid": true,
        "status": "deliverable",
        "score": 95
      },
      {
        "email": "[email protected]",
        "isValid": false,
        "status": "undeliverable",
        "score": 2
      }
    ],
    "createdAt": "2025-03-15T14:00:00.000Z",
    "completedAt": "2025-03-15T14:12:00.000Z"
  }
}

GET

/email-validation/credits

READ

Retourne le solde de credits de validation email restants.

Exemple curl

curl -X GET https://api.sigmabox.fr/email-validation/credits \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "credits": 4820,
    "plan": "business",
    "monthlyAllocation": 5000,
    "resetDate": "2025-04-01T00:00:00.000Z"
  }
}

GET

/email-validation/bulk/:id/export

READ

Exporte les resultats d'une validation bulk au format CSV ou en liste d'emails.

Parametres de requete

Parametre	Type	Requis	Description
`format`	string	Non	Format d'export : csv (defaut) ou emails (liste texte brut)
`filter`	string	Non	Filtrer par statut : VALID, INVALID, RISKY, UNKNOWN, ERROR (separes par virgules)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/email-validation/bulk/BULK_ID/export?format=csv&filter=VALID,RISKY" \
  -o validation.csv

Reponse

Email,Statut,Valide,Jetable,Catch-All,Role,Score,Statut API
[email protected],VALID,true,false,false,false,95,deliverable
[email protected],RISKY,true,false,true,true,62,risky

Liens Courts

GET

/short-links

READ

Liste tous vos liens courts.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)

Exemple curl

curl -X GET "https://api.sigmabox.fr/short-links?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "lnk_abc123",
        "shortUrl": "https://sgbx.fr/promo25",
        "originalUrl": "https://entreprise.fr/offre-speciale-2025",
        "clicks": 187,
        "createdAt": "2025-03-01T12:00:00.000Z"
      },
      {
        "id": "lnk_def456",
        "shortUrl": "https://sgbx.fr/demo",
        "originalUrl": "https://entreprise.fr/demander-demo",
        "clicks": 54,
        "createdAt": "2025-03-10T08:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

POST

/short-links

WRITE

Cree un nouveau lien court.

Corps de la requete

Parametre	Type	Requis	Description
`originalUrl`	string	Oui	URL longue a raccourcir
`slug`	string	Non	Slug personnalise (optionnel, genere automatiquement sinon)

Exemple curl

curl -X POST https://api.sigmabox.fr/short-links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://entreprise.fr/offre-speciale-2025", "slug": "promo25"}'

Reponse

{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://sgbx.fr/promo25",
    "originalUrl": "https://entreprise.fr/offre-speciale-2025",
    "clicks": 0,
    "createdAt": "2025-03-21T10:00:00.000Z"
  }
}

GET

/short-links/:id

READ

Retourne le detail d'un lien court.

Exemple curl

curl -X GET https://api.sigmabox.fr/short-links/lnk_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://sgbx.fr/promo25",
    "originalUrl": "https://entreprise.fr/offre-speciale-2025",
    "clicks": 187,
    "lastClickAt": "2025-03-21T09:45:00.000Z",
    "createdAt": "2025-03-01T12:00:00.000Z"
  }
}

PATCH

/short-links/:id

WRITE

Met a jour un lien court existant.

Corps de la requete

Parametre	Type	Requis	Description
`originalUrl`	string	Non	Nouvelle URL de destination
`slug`	string	Non	Nouveau slug personnalise

Exemple curl

curl -X PATCH https://api.sigmabox.fr/short-links/lnk_abc123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://entreprise.fr/nouvelle-offre"}'

Reponse

{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://sgbx.fr/promo25",
    "originalUrl": "https://entreprise.fr/nouvelle-offre",
    "updatedAt": "2025-03-21T10:30:00.000Z"
  }
}

DELETE

/short-links/:id

WRITE

Supprime un lien court. Les redirections cesseront immediatement.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/short-links/lnk_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Lien court supprime avec succes."
  }
}

GET

/short-links/:id/analytics

READ

Retourne les statistiques de clics d'un lien court.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30)

Exemple curl

curl -X GET "https://api.sigmabox.fr/short-links/lnk_abc123/analytics?days=7" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "linkId": "lnk_abc123",
    "period": {
      "from": "2025-03-14",
      "to": "2025-03-21"
    },
    "totalClicks": 42,
    "daily": [
      {
        "date": "2025-03-21",
        "clicks": 8
      },
      {
        "date": "2025-03-20",
        "clicks": 5
      },
      {
        "date": "2025-03-19",
        "clicks": 7
      }
    ],
    "referrers": [
      {
        "source": "gmail.com",
        "clicks": 20
      },
      {
        "source": "outlook.com",
        "clicks": 15
      },
      {
        "source": "direct",
        "clicks": 7
      }
    ]
  }
}

GET

/short-links/:id/export

READ

Exporte les analytics d'un lien court au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/short-links/LINK_ID/export?days=30" \
  -o link-analytics.csv

Reponse

Date,Clics,Visiteurs uniques,Pays,Appareil,Navigateur,Source
2025-03-21,8,6,France,Desktop,Chrome,gmail.com
2025-03-20,5,4,Belgique,Mobile,Safari,outlook.com
2025-03-19,7,5,France,Desktop,Firefox,direct

GET

/short-links/overview/export

READ

Exporte les analytics de tous les liens courts au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/short-links/overview/export?days=30" \
  -o links-overview.csv

Reponse

Date,Lien,Clics,Visiteurs uniques,Pays,Appareil,Navigateur,Source
2025-03-21,https://sgbx.fr/promo25,8,6,France,Desktop,Chrome,gmail.com
2025-03-21,https://sgbx.fr/demo,3,2,Belgique,Mobile,Safari,outlook.com
2025-03-20,https://sgbx.fr/promo25,5,4,France,Desktop,Firefox,direct

Analytics

GET

/analytics/overview

READ

Retourne une vue d'ensemble de vos statistiques globales.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 90)

Exemple curl

curl -X GET "https://api.sigmabox.fr/analytics/overview?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "period": {
      "from": "2025-02-19",
      "to": "2025-03-21"
    },
    "signatures": {
      "total": 5,
      "active": 3
    },
    "campaigns": {
      "total": 8,
      "active": 4,
      "totalClicks": 1250,
      "totalImpressions": 34200,
      "avgCtr": 3.65
    },
    "emailValidation": {
      "totalValidated": 2300,
      "creditsUsed": 2300,
      "creditsRemaining": 2700
    },
    "shortLinks": {
      "total": 12,
      "totalClicks": 890
    }
  }
}

GET

/analytics/signatures/:id

READ

Retourne les statistiques detaillees d'une signature specifique.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 90)

Exemple curl

curl -X GET "https://api.sigmabox.fr/analytics/signatures/sig_abc123?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "signatureId": "sig_abc123",
    "signatureName": "Signature principale",
    "period": {
      "from": "2025-02-19",
      "to": "2025-03-21"
    },
    "totals": {
      "impressions": 12400,
      "clicks": 520,
      "ctr": 4.19
    },
    "daily": [
      {
        "date": "2025-03-21",
        "impressions": 410,
        "clicks": 22,
        "ctr": 5.37
      },
      {
        "date": "2025-03-20",
        "impressions": 395,
        "clicks": 18,
        "ctr": 4.56
      }
    ],
    "topCampaigns": [
      {
        "id": "cmp_xyz789",
        "name": "Promo Ete 2025",
        "clicks": 342
      }
    ]
  }
}

GET

/analytics/overview/export

READ

Exporte les analytics overview au format CSV sur une periode donnee.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/analytics/overview/export?days=30" \
  -o analytics.csv

Reponse

Date,Signature,Vues,Ouvertures uniques,Pays,OS,Client mail
2025-03-21,Signature principale,410,220,France,Windows,Outlook
2025-03-21,Signature marketing,180,95,Belgique,macOS,Gmail
2025-03-20,Signature principale,395,210,France,Windows,Thunderbird

GET

/analytics/signatures/:id/export

READ

Exporte les analytics d'une signature specifique au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/analytics/signatures/SIG_ID/export?days=7" \
  -o signature-analytics.csv

Reponse

Date,Vues,Ouvertures uniques,Pays,OS,Client mail
2025-03-21,410,220,France,Windows,Outlook
2025-03-20,395,210,France,macOS,Gmail
2025-03-19,380,195,Belgique,Windows,Thunderbird

Organisations

GET

/organizations

READ

Liste toutes les organisations de votre holding.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20)

Exemple curl

curl -X GET "https://api.sigmabox.fr/organizations?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "organizations": [
      {
        "id": "org_001",
        "name": "Filiale France",
        "membersCount": 12,
        "signaturesCount": 5,
        "createdAt": "2025-01-10T09:00:00.000Z"
      },
      {
        "id": "org_002",
        "name": "Filiale Belgique",
        "membersCount": 4,
        "signaturesCount": 2,
        "createdAt": "2025-02-20T14:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

POST

/organizations

ADMIN

Cree une nouvelle organisation dans votre holding.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Oui	Nom de l'organisation

Exemple curl

curl -X POST https://api.sigmabox.fr/organizations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Filiale Suisse"}'

Reponse

{
  "success": true,
  "data": {
    "id": "org_003",
    "name": "Filiale Suisse",
    "membersCount": 0,
    "signaturesCount": 0,
    "createdAt": "2025-03-21T10:00:00.000Z"
  }
}

GET

/organizations/:id

READ

Retourne le detail d'une organisation.

Exemple curl

curl -X GET https://api.sigmabox.fr/organizations/org_001 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "org_001",
    "name": "Filiale France",
    "membersCount": 12,
    "signaturesCount": 5,
    "members": [
      {
        "id": "usr_m01",
        "email": "[email protected]",
        "role": "admin"
      },
      {
        "id": "usr_m02",
        "email": "[email protected]",
        "role": "member"
      }
    ],
    "createdAt": "2025-01-10T09:00:00.000Z",
    "updatedAt": "2025-03-15T16:00:00.000Z"
  }
}

PATCH

/organizations/:id

ADMIN

Met a jour les informations d'une organisation.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Non	Nouveau nom de l'organisation

Exemple curl

curl -X PATCH https://api.sigmabox.fr/organizations/org_001 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Filiale France — Paris"}'

Reponse

{
  "success": true,
  "data": {
    "id": "org_001",
    "name": "Filiale France -- Paris",
    "updatedAt": "2025-03-21T11:00:00.000Z"
  }
}

DELETE

/organizations/:id

ADMIN

Supprime une organisation. Tous les membres seront dissocies.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/organizations/org_003 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Organisation supprimee avec succes."
  }
}

POST

/organizations/transfer

ADMIN

Transfere une signature ou une campagne d'une organisation a une autre.

Corps de la requete

Parametre	Type	Requis	Description
`type`	string	Oui	"signature" ou "campaign"
`resourceId`	string	Oui	Identifiant de la ressource a transferer
`fromOrganizationId`	string	Oui	Organisation source
`toOrganizationId`	string	Oui	Organisation de destination

Exemple curl

curl -X POST https://api.sigmabox.fr/organizations/transfer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "signature",
    "resourceId": "sig_abc123",
    "fromOrganizationId": "org_001",
    "toOrganizationId": "org_002"
  }'

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Signature transferee de Filiale France vers Filiale Belgique.",
    "resourceId": "sig_abc123",
    "fromOrganizationId": "org_001",
    "toOrganizationId": "org_002"
  }
}

Credits

GET

/credits/balance

READ

Retourne le solde actuel de credits de votre compte.

Exemple curl

curl -X GET https://api.sigmabox.fr/credits/balance \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "balance": 4820,
    "plan": "business",
    "monthlyAllocation": 5000,
    "used": 180,
    "resetDate": "2025-04-01T00:00:00.000Z"
  }
}

GET

/credits/purchases

READ

Retourne l'historique de vos achats de credits.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20)

Exemple curl

curl -X GET "https://api.sigmabox.fr/credits/purchases?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "purchases": [
      {
        "id": "pur_001",
        "credits": 5000,
        "amount": 49,
        "currency": "EUR",
        "status": "completed",
        "createdAt": "2025-03-01T00:00:00.000Z"
      },
      {
        "id": "pur_002",
        "credits": 1000,
        "amount": 12,
        "currency": "EUR",
        "status": "completed",
        "createdAt": "2025-02-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

Demarrage rapide

URL de base

Toutes les requetes doivent etre envoyees a l'URL de base suivante :

https://api.sigmabox.fr

Authentification

Authentifiez vos requetes en incluant votre cle API dans l'en-tete HTTP. Deux methodes sont supportees :

# Methode 1 — En-tete X-API-Key (recommande)
curl -H "X-API-Key: sk_live_xxx" https://api.sigmabox.fr/me

# Methode 2 — En-tete Authorization Bearer
curl -H "Authorization: Bearer sk_live_xxx" https://api.sigmabox.fr/me

Vous n'avez pas encore de cle API ? Creez-en une gratuitement depuis votre tableau de bord Sigmabox.

Format de reponse

Toutes les reponses sont en JSON et suivent un format standardise. Les reponses reussies contiennent {"success": true, "data": {...}}. Les erreurs contiennent {"success": false, "error": "..."}.

Succes

{
  "success": true,
  "data": {
    "id": "xxx",
    "...": "..."
  }
}

Erreur

{
  "success": false,
  "error": "Cle API invalide ou manquante."
}

Limites de debit

Les limites suivantes s'appliquent pour proteger l'infrastructure :

Limite	Valeur
Par adresse IP	60 requetes / minute
Par cle API	300 requetes / minute

Scopes (permissions)

Chaque cle API possede un ou plusieurs scopes qui determinent les actions autorisees :

Scope	Description
READ	Lecture des donnees (signatures, campagnes, analytics, etc.)
WRITE	Creation, modification et suppression de ressources
ADMIN	Gestion des organisations, transferts et parametres avances

Profil

GET

/me

READ

Retourne les informations du profil associe a la cle API utilisee.

Exemple curl

curl -X GET https://api.sigmabox.fr/me \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Jean Dupont",
    "company": "Entreprise SAS",
    "isPremium": true,
    "plan": "business",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Signatures

GET

/signatures

READ

Liste toutes les signatures de votre compte.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)

Exemple curl

curl -X GET "https://api.sigmabox.fr/signatures?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "signatures": [
      {
        "id": "sig_abc123",
        "name": "Signature principale",
        "isActive": true,
        "isBlurred": false,
        "createdAt": "2025-02-01T08:00:00.000Z",
        "updatedAt": "2025-03-10T14:22:00.000Z"
      },
      {
        "id": "sig_def456",
        "name": "Signature marketing",
        "isActive": false,
        "isBlurred": false,
        "createdAt": "2025-02-15T09:30:00.000Z",
        "updatedAt": "2025-03-12T11:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

GET

/signatures/:id

READ

Retourne le detail d'une signature specifique.

Exemple curl

curl -X GET https://api.sigmabox.fr/signatures/sig_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "sig_abc123",
    "name": "Signature principale",
    "isActive": true,
    "isBlurred": false,
    "html": "<table>...</table>",
    "campaigns": [
      "cmp_xyz789"
    ],
    "createdAt": "2025-02-01T08:00:00.000Z",
    "updatedAt": "2025-03-10T14:22:00.000Z"
  }
}

PATCH

/signatures/:id

WRITE

Met a jour les proprietes d'une signature.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Non	Nouveau nom de la signature
`isActive`	boolean	Non	Activer ou desactiver la signature
`isBlurred`	boolean	Non	Flouter ou non la signature

Exemple curl

curl -X PATCH https://api.sigmabox.fr/signatures/sig_abc123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Signature mise a jour", "isActive": true}'

Reponse

{
  "success": true,
  "data": {
    "id": "sig_abc123",
    "name": "Signature mise a jour",
    "isActive": true,
    "isBlurred": false,
    "updatedAt": "2025-03-21T09:15:00.000Z"
  }
}

DELETE

/signatures/:id

WRITE

Supprime definitivement une signature.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/signatures/sig_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Signature supprimee avec succes."
  }
}

POST

/signatures/:id/toggle-active

WRITE

Bascule l'etat actif/inactif d'une signature. Pratique pour activer ou desactiver rapidement.

Exemple curl

curl -X POST https://api.sigmabox.fr/signatures/sig_abc123/toggle-active \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "sig_abc123",
    "isActive": false,
    "message": "Signature desactivee."
  }
}

GET

/signatures/:id/download

READ

Telecharge le fichier HTML de la signature. Le contenu est retourne directement en text/html.

Exemple curl

curl -X GET https://api.sigmabox.fr/signatures/sig_abc123/download \
  -H "X-API-Key: YOUR_API_KEY" \
  -o signature.html

Reponse

<!-- Le fichier HTML de la signature est telecharge directement -->
<table style="font-family: Arial, sans-serif;">
  <tr>
    <td>
      <strong>Jean Dupont</strong><br/>
      Directeur Commercial — Entreprise SAS
    </td>
  </tr>
</table>

Campagnes

GET

/campaigns

READ

Liste toutes les campagnes avec filtrage et pagination.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)
`search`	string	Non	Recherche par nom de campagne
`isActive`	boolean	Non	Filtrer par etat actif/inactif
`signatureId`	string	Non	Filtrer par identifiant de signature

Exemple curl

curl -X GET "https://api.sigmabox.fr/campaigns?page=1&limit=10&isActive=true" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "cmp_xyz789",
        "name": "Promo Ete 2025",
        "isActive": true,
        "signatureId": "sig_abc123",
        "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
        "targetUrl": "https://entreprise.fr/promo",
        "clicks": 342,
        "impressions": 8920,
        "createdAt": "2025-06-01T07:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1
    }
  }
}

POST

/campaigns

WRITE

Cree une nouvelle campagne de banniere.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Oui	Nom de la campagne
`signatureId`	string	Oui	Identifiant de la signature associee
`bannerUrl`	string	Oui	URL de l'image de la banniere
`targetUrl`	string	Oui	URL de destination au clic
`isActive`	boolean	Non	Activer immediatement (defaut : true)

Exemple curl

curl -X POST https://api.sigmabox.fr/campaigns \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promo Ete 2025",
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/promo",
    "isActive": true
  }'

Reponse

{
  "success": true,
  "data": {
    "id": "cmp_xyz789",
    "name": "Promo Ete 2025",
    "isActive": true,
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/promo",
    "clicks": 0,
    "impressions": 0,
    "createdAt": "2025-06-01T07:00:00.000Z"
  }
}

GET

/campaigns/:id

READ

Retourne le detail d'une campagne specifique.

Exemple curl

curl -X GET https://api.sigmabox.fr/campaigns/cmp_xyz789 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "cmp_xyz789",
    "name": "Promo Ete 2025",
    "isActive": true,
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/promo",
    "clicks": 342,
    "impressions": 8920,
    "ctr": 3.83,
    "createdAt": "2025-06-01T07:00:00.000Z",
    "updatedAt": "2025-06-15T10:00:00.000Z"
  }
}

PATCH

/campaigns/:id

WRITE

Met a jour une campagne existante.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Non	Nouveau nom
`bannerUrl`	string	Non	Nouvelle URL de banniere
`targetUrl`	string	Non	Nouvelle URL de destination
`isActive`	boolean	Non	Activer ou desactiver

Exemple curl

curl -X PATCH https://api.sigmabox.fr/campaigns/cmp_xyz789 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Promo Automne 2025", "targetUrl": "https://entreprise.fr/automne"}'

Reponse

{
  "success": true,
  "data": {
    "id": "cmp_xyz789",
    "name": "Promo Automne 2025",
    "isActive": true,
    "signatureId": "sig_abc123",
    "bannerUrl": "https://cdn.sigmabox.fr/banners/promo-ete.png",
    "targetUrl": "https://entreprise.fr/automne",
    "updatedAt": "2025-09-01T08:00:00.000Z"
  }
}

DELETE

/campaigns/:id

WRITE

Supprime definitivement une campagne.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/campaigns/cmp_xyz789 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Campagne supprimee avec succes."
  }
}

GET

/campaigns/:id/analytics

READ

Retourne les statistiques detaillees d'une campagne sur une periode donnee.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 90)

Exemple curl

curl -X GET "https://api.sigmabox.fr/campaigns/cmp_xyz789/analytics?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "campaignId": "cmp_xyz789",
    "period": {
      "from": "2025-05-22",
      "to": "2025-06-21"
    },
    "totals": {
      "clicks": 342,
      "impressions": 8920,
      "ctr": 3.83
    },
    "daily": [
      {
        "date": "2025-06-21",
        "clicks": 18,
        "impressions": 310,
        "ctr": 5.81
      },
      {
        "date": "2025-06-20",
        "clicks": 12,
        "impressions": 295,
        "ctr": 4.07
      }
    ]
  }
}

GET

/campaigns/export

READ

Exporte les donnees des campagnes au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30)
`campaignIds`	string	Non	IDs de campagnes separes par virgules
`signatureIds`	string	Non	IDs de signatures separes par virgules

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/campaigns/export?days=30" \
  -o campaigns.csv

Reponse

Date,Campagne,Signature,Clics,Impressions,CTR
2025-03-21,Promo Ete 2025,Signature principale,18,310,5.81
2025-03-20,Promo Ete 2025,Signature principale,12,295,4.07

Validation Email

POST

/email-validation/validate

WRITE

Valide une adresse email en temps reel. Consomme 1 credit par verification.

Corps de la requete

Parametre	Type	Requis	Description
`email`	string	Oui	Adresse email a verifier

Exemple curl

curl -X POST https://api.sigmabox.fr/email-validation/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Reponse

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "isValid": true,
    "status": "deliverable",
    "score": 98,
    "checks": {
      "syntax": true,
      "mxRecords": true,
      "disposable": false,
      "roleAccount": false,
      "freeProvider": false
    },
    "provider": "OVH",
    "verifiedAt": "2025-03-21T10:00:00.000Z"
  }
}

GET

/email-validation/history

READ

Retourne l'historique de vos validations email unitaires.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)

Exemple curl

curl -X GET "https://api.sigmabox.fr/email-validation/history?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "validations": [
      {
        "email": "[email protected]",
        "isValid": true,
        "status": "deliverable",
        "score": 98,
        "verifiedAt": "2025-03-21T10:00:00.000Z"
      },
      {
        "email": "[email protected]",
        "isValid": false,
        "status": "disposable",
        "score": 5,
        "verifiedAt": "2025-03-21T09:55:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 54,
      "totalPages": 6
    }
  }
}

GET

/email-validation/bulk

READ

Liste tous les traitements de validation en masse (bulk).

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20)

Exemple curl

curl -X GET "https://api.sigmabox.fr/email-validation/bulk?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "bulkJobs": [
      {
        "id": "bulk_001",
        "fileName": "contacts_mars.csv",
        "totalEmails": 1500,
        "processed": 1500,
        "valid": 1320,
        "invalid": 180,
        "status": "completed",
        "createdAt": "2025-03-15T14:00:00.000Z",
        "completedAt": "2025-03-15T14:12:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 3,
      "totalPages": 1
    }
  }
}

GET

/email-validation/bulk/:id

READ

Retourne le detail et les resultats d'un traitement bulk specifique.

Exemple curl

curl -X GET https://api.sigmabox.fr/email-validation/bulk/bulk_001 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "bulk_001",
    "fileName": "contacts_mars.csv",
    "totalEmails": 1500,
    "processed": 1500,
    "valid": 1320,
    "invalid": 180,
    "status": "completed",
    "results": [
      {
        "email": "[email protected]",
        "isValid": true,
        "status": "deliverable",
        "score": 95
      },
      {
        "email": "[email protected]",
        "isValid": false,
        "status": "undeliverable",
        "score": 2
      }
    ],
    "createdAt": "2025-03-15T14:00:00.000Z",
    "completedAt": "2025-03-15T14:12:00.000Z"
  }
}

GET

/email-validation/credits

READ

Retourne le solde de credits de validation email restants.

Exemple curl

curl -X GET https://api.sigmabox.fr/email-validation/credits \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "credits": 4820,
    "plan": "business",
    "monthlyAllocation": 5000,
    "resetDate": "2025-04-01T00:00:00.000Z"
  }
}

GET

/email-validation/bulk/:id/export

READ

Exporte les resultats d'une validation bulk au format CSV ou en liste d'emails.

Parametres de requete

Parametre	Type	Requis	Description
`format`	string	Non	Format d'export : csv (defaut) ou emails (liste texte brut)
`filter`	string	Non	Filtrer par statut : VALID, INVALID, RISKY, UNKNOWN, ERROR (separes par virgules)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/email-validation/bulk/BULK_ID/export?format=csv&filter=VALID,RISKY" \
  -o validation.csv

Reponse

Email,Statut,Valide,Jetable,Catch-All,Role,Score,Statut API
[email protected],VALID,true,false,false,false,95,deliverable
[email protected],RISKY,true,false,true,true,62,risky

Liens Courts

GET

/short-links

READ

Liste tous vos liens courts.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20, max : 100)

Exemple curl

curl -X GET "https://api.sigmabox.fr/short-links?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "lnk_abc123",
        "shortUrl": "https://sgbx.fr/promo25",
        "originalUrl": "https://entreprise.fr/offre-speciale-2025",
        "clicks": 187,
        "createdAt": "2025-03-01T12:00:00.000Z"
      },
      {
        "id": "lnk_def456",
        "shortUrl": "https://sgbx.fr/demo",
        "originalUrl": "https://entreprise.fr/demander-demo",
        "clicks": 54,
        "createdAt": "2025-03-10T08:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

POST

/short-links

WRITE

Cree un nouveau lien court.

Corps de la requete

Parametre	Type	Requis	Description
`originalUrl`	string	Oui	URL longue a raccourcir
`slug`	string	Non	Slug personnalise (optionnel, genere automatiquement sinon)

Exemple curl

curl -X POST https://api.sigmabox.fr/short-links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://entreprise.fr/offre-speciale-2025", "slug": "promo25"}'

Reponse

{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://sgbx.fr/promo25",
    "originalUrl": "https://entreprise.fr/offre-speciale-2025",
    "clicks": 0,
    "createdAt": "2025-03-21T10:00:00.000Z"
  }
}

GET

/short-links/:id

READ

Retourne le detail d'un lien court.

Exemple curl

curl -X GET https://api.sigmabox.fr/short-links/lnk_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://sgbx.fr/promo25",
    "originalUrl": "https://entreprise.fr/offre-speciale-2025",
    "clicks": 187,
    "lastClickAt": "2025-03-21T09:45:00.000Z",
    "createdAt": "2025-03-01T12:00:00.000Z"
  }
}

PATCH

/short-links/:id

WRITE

Met a jour un lien court existant.

Corps de la requete

Parametre	Type	Requis	Description
`originalUrl`	string	Non	Nouvelle URL de destination
`slug`	string	Non	Nouveau slug personnalise

Exemple curl

curl -X PATCH https://api.sigmabox.fr/short-links/lnk_abc123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://entreprise.fr/nouvelle-offre"}'

Reponse

{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://sgbx.fr/promo25",
    "originalUrl": "https://entreprise.fr/nouvelle-offre",
    "updatedAt": "2025-03-21T10:30:00.000Z"
  }
}

DELETE

/short-links/:id

WRITE

Supprime un lien court. Les redirections cesseront immediatement.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/short-links/lnk_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Lien court supprime avec succes."
  }
}

GET

/short-links/:id/analytics

READ

Retourne les statistiques de clics d'un lien court.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30)

Exemple curl

curl -X GET "https://api.sigmabox.fr/short-links/lnk_abc123/analytics?days=7" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "linkId": "lnk_abc123",
    "period": {
      "from": "2025-03-14",
      "to": "2025-03-21"
    },
    "totalClicks": 42,
    "daily": [
      {
        "date": "2025-03-21",
        "clicks": 8
      },
      {
        "date": "2025-03-20",
        "clicks": 5
      },
      {
        "date": "2025-03-19",
        "clicks": 7
      }
    ],
    "referrers": [
      {
        "source": "gmail.com",
        "clicks": 20
      },
      {
        "source": "outlook.com",
        "clicks": 15
      },
      {
        "source": "direct",
        "clicks": 7
      }
    ]
  }
}

GET

/short-links/:id/export

READ

Exporte les analytics d'un lien court au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/short-links/LINK_ID/export?days=30" \
  -o link-analytics.csv

Reponse

Date,Clics,Visiteurs uniques,Pays,Appareil,Navigateur,Source
2025-03-21,8,6,France,Desktop,Chrome,gmail.com
2025-03-20,5,4,Belgique,Mobile,Safari,outlook.com
2025-03-19,7,5,France,Desktop,Firefox,direct

GET

/short-links/overview/export

READ

Exporte les analytics de tous les liens courts au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/short-links/overview/export?days=30" \
  -o links-overview.csv

Reponse

Date,Lien,Clics,Visiteurs uniques,Pays,Appareil,Navigateur,Source
2025-03-21,https://sgbx.fr/promo25,8,6,France,Desktop,Chrome,gmail.com
2025-03-21,https://sgbx.fr/demo,3,2,Belgique,Mobile,Safari,outlook.com
2025-03-20,https://sgbx.fr/promo25,5,4,France,Desktop,Firefox,direct

Analytics

GET

/analytics/overview

READ

Retourne une vue d'ensemble de vos statistiques globales.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 90)

Exemple curl

curl -X GET "https://api.sigmabox.fr/analytics/overview?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "period": {
      "from": "2025-02-19",
      "to": "2025-03-21"
    },
    "signatures": {
      "total": 5,
      "active": 3
    },
    "campaigns": {
      "total": 8,
      "active": 4,
      "totalClicks": 1250,
      "totalImpressions": 34200,
      "avgCtr": 3.65
    },
    "emailValidation": {
      "totalValidated": 2300,
      "creditsUsed": 2300,
      "creditsRemaining": 2700
    },
    "shortLinks": {
      "total": 12,
      "totalClicks": 890
    }
  }
}

GET

/analytics/signatures/:id

READ

Retourne les statistiques detaillees d'une signature specifique.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 90)

Exemple curl

curl -X GET "https://api.sigmabox.fr/analytics/signatures/sig_abc123?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "signatureId": "sig_abc123",
    "signatureName": "Signature principale",
    "period": {
      "from": "2025-02-19",
      "to": "2025-03-21"
    },
    "totals": {
      "impressions": 12400,
      "clicks": 520,
      "ctr": 4.19
    },
    "daily": [
      {
        "date": "2025-03-21",
        "impressions": 410,
        "clicks": 22,
        "ctr": 5.37
      },
      {
        "date": "2025-03-20",
        "impressions": 395,
        "clicks": 18,
        "ctr": 4.56
      }
    ],
    "topCampaigns": [
      {
        "id": "cmp_xyz789",
        "name": "Promo Ete 2025",
        "clicks": 342
      }
    ]
  }
}

GET

/analytics/overview/export

READ

Exporte les analytics overview au format CSV sur une periode donnee.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/analytics/overview/export?days=30" \
  -o analytics.csv

Reponse

Date,Signature,Vues,Ouvertures uniques,Pays,OS,Client mail
2025-03-21,Signature principale,410,220,France,Windows,Outlook
2025-03-21,Signature marketing,180,95,Belgique,macOS,Gmail
2025-03-20,Signature principale,395,210,France,Windows,Thunderbird

GET

/analytics/signatures/:id/export

READ

Exporte les analytics d'une signature specifique au format CSV.

Parametres de requete

Parametre	Type	Requis	Description
`days`	number	Non	Nombre de jours d'historique (defaut : 30, max : 365)

Exemple curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.sigmabox.fr/analytics/signatures/SIG_ID/export?days=7" \
  -o signature-analytics.csv

Reponse

Date,Vues,Ouvertures uniques,Pays,OS,Client mail
2025-03-21,410,220,France,Windows,Outlook
2025-03-20,395,210,France,macOS,Gmail
2025-03-19,380,195,Belgique,Windows,Thunderbird

Organisations

GET

/organizations

READ

Liste toutes les organisations de votre holding.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20)

Exemple curl

curl -X GET "https://api.sigmabox.fr/organizations?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "organizations": [
      {
        "id": "org_001",
        "name": "Filiale France",
        "membersCount": 12,
        "signaturesCount": 5,
        "createdAt": "2025-01-10T09:00:00.000Z"
      },
      {
        "id": "org_002",
        "name": "Filiale Belgique",
        "membersCount": 4,
        "signaturesCount": 2,
        "createdAt": "2025-02-20T14:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

POST

/organizations

ADMIN

Cree une nouvelle organisation dans votre holding.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Oui	Nom de l'organisation

Exemple curl

curl -X POST https://api.sigmabox.fr/organizations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Filiale Suisse"}'

Reponse

{
  "success": true,
  "data": {
    "id": "org_003",
    "name": "Filiale Suisse",
    "membersCount": 0,
    "signaturesCount": 0,
    "createdAt": "2025-03-21T10:00:00.000Z"
  }
}

GET

/organizations/:id

READ

Retourne le detail d'une organisation.

Exemple curl

curl -X GET https://api.sigmabox.fr/organizations/org_001 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "id": "org_001",
    "name": "Filiale France",
    "membersCount": 12,
    "signaturesCount": 5,
    "members": [
      {
        "id": "usr_m01",
        "email": "[email protected]",
        "role": "admin"
      },
      {
        "id": "usr_m02",
        "email": "[email protected]",
        "role": "member"
      }
    ],
    "createdAt": "2025-01-10T09:00:00.000Z",
    "updatedAt": "2025-03-15T16:00:00.000Z"
  }
}

PATCH

/organizations/:id

ADMIN

Met a jour les informations d'une organisation.

Corps de la requete

Parametre	Type	Requis	Description
`name`	string	Non	Nouveau nom de l'organisation

Exemple curl

curl -X PATCH https://api.sigmabox.fr/organizations/org_001 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Filiale France — Paris"}'

Reponse

{
  "success": true,
  "data": {
    "id": "org_001",
    "name": "Filiale France -- Paris",
    "updatedAt": "2025-03-21T11:00:00.000Z"
  }
}

DELETE

/organizations/:id

ADMIN

Supprime une organisation. Tous les membres seront dissocies.

Exemple curl

curl -X DELETE https://api.sigmabox.fr/organizations/org_003 \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Organisation supprimee avec succes."
  }
}

POST

/organizations/transfer

ADMIN

Transfere une signature ou une campagne d'une organisation a une autre.

Corps de la requete

Parametre	Type	Requis	Description
`type`	string	Oui	"signature" ou "campaign"
`resourceId`	string	Oui	Identifiant de la ressource a transferer
`fromOrganizationId`	string	Oui	Organisation source
`toOrganizationId`	string	Oui	Organisation de destination

Exemple curl

curl -X POST https://api.sigmabox.fr/organizations/transfer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "signature",
    "resourceId": "sig_abc123",
    "fromOrganizationId": "org_001",
    "toOrganizationId": "org_002"
  }'

Reponse

{
  "success": true,
  "data": {
    "success": true,
    "message": "Signature transferee de Filiale France vers Filiale Belgique.",
    "resourceId": "sig_abc123",
    "fromOrganizationId": "org_001",
    "toOrganizationId": "org_002"
  }
}

Credits

GET

/credits/balance

READ

Retourne le solde actuel de credits de votre compte.

Exemple curl

curl -X GET https://api.sigmabox.fr/credits/balance \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "balance": 4820,
    "plan": "business",
    "monthlyAllocation": 5000,
    "used": 180,
    "resetDate": "2025-04-01T00:00:00.000Z"
  }
}

GET

/credits/purchases

READ

Retourne l'historique de vos achats de credits.

Parametres de requete

Parametre	Type	Requis	Description
`page`	number	Non	Numero de page (defaut : 1)
`limit`	number	Non	Nombre de resultats par page (defaut : 20)

Exemple curl

curl -X GET "https://api.sigmabox.fr/credits/purchases?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Reponse

{
  "success": true,
  "data": {
    "purchases": [
      {
        "id": "pur_001",
        "credits": 5000,
        "amount": 49,
        "currency": "EUR",
        "status": "completed",
        "createdAt": "2025-03-01T00:00:00.000Z"
      },
      {
        "id": "pur_002",
        "credits": 1000,
        "amount": 12,
        "currency": "EUR",
        "status": "completed",
        "createdAt": "2025-02-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

Documentation API

Demarrage rapide

URL de base

Authentification

Format de reponse

Succes

Erreur

Limites de debit

Scopes (permissions)

Profil

Exemple curl

Reponse

Signatures

Parametres de requete

Exemple curl

Reponse

Exemple curl

Reponse

Corps de la requete

Exemple curl

Reponse

Exemple curl

Reponse

Exemple curl

Reponse

Exemple curl

Reponse

Campagnes

Parametres de requete

Exemple curl

Reponse

Corps de la requete

Exemple curl

Reponse

Exemple curl

Reponse

Corps de la requete

Exemple curl

Reponse

Exemple curl

Reponse

Parametres de requete

Exemple curl

Reponse

Parametres de requete

Exemple curl

Reponse

Validation Email

Corps de la requete

Exemple curl

Reponse

Parametres de requete

Exemple curl

Reponse

Parametres de requete

Exemple curl

Reponse

Exemple curl

Reponse

Exemple curl

Reponse

Parametres de requete

Exemple curl

Reponse

Liens Courts

Parametres de requete

Exemple curl

Reponse

Corps de la requete

Exemple curl

Reponse

Exemple curl

Reponse

Corps de la requete

Exemple curl

Reponse

Exemple curl

Reponse

Parametres de requete

Exemple curl