Documentation d'API Gustave

L'API Gustave permet d'accéder aux fonctionnalités de la plateforme d'automatisation commerciale. Cette API utilise une authentification par token et retourne des données au format JSON.

Base URL: https://gustave.email/api

Format des Réponses

Toutes les réponses de l'API suivent un format standardisé incluant un indicateur de succès :

Réponse réussie

{
    "success": true,
    "data": { ... },
    "meta": { ... }  // si applicable
}

Réponse d'erreur

{
    "success": false,
    "error": "Message d'erreur",
    "messages": { ... }  // détails de validation si applicable
}

Authentification

Obtenir un Token API

1. Connectez-vous à votre compte Gustave
2. Accédez à Paramètres > API
3. Créez un nouveau token en sélectionnant les permissions nécessaires
4. Copiez le token généré (il ne sera plus visible après)

Utiliser le Token

Incluez le token API en tant que paramètre api_key dans l'URL de chaque requête :

https://gustave.email/api/contacts?api_key=votre-token-api

Alternativement, vous pouvez aussi utiliser l'en-tête Authorization :

Authorization: Bearer votre-token-api

Permissions Disponibles

• read : Lecture des données (contacts, emails, statistiques)
• create : Création de contacts et éléments de blocklist
• delete : Suppression d'éléments de blocklist

Endpoints Disponibles

1. Utilisateur

GET /api/me

Récupère les informations de l'utilisateur connecté et la liste de ses agents.

Réponse :

{
    "user": {
        "id": "aBc123Xy",
        "name": "Pierre Martin",
        "email": "pierre.martin@example.com",
        "created_at": "2024-01-15T10:30:00Z"
    },
    "agents": [
        {
            "id": "dEf456Zw",
            "name": "Gustave Commercial",
            "firstname": "Gustave",
            "lastname": "Commercial",
            "status": "active",
            "internal_note": "B2B SaaS",
            "is_active": true
        },
        {
            "id": "gHi789Uv",
            "name": "Sophie Marketing",
            "firstname": "Sophie",
            "lastname": "Marketing",
            "status": "paused",
            "internal_note": null,
            "is_active": false
        }
    ],
    "meta": {
        "total_agents": 2,
        "active_agents": 1
    }
}

Champs des agents :

• internal_note : Note personnelle pour identifier l'agent (nullable, 20 caractères max)

Statuts d'agent disponibles :

• active : Agent actif et opérationnel
• paused : Agent en pause
• setup : Agent en cours de configuration
• inactive : Agent inactif

2. Contacts

GET /api/contacts

Récupère la liste des contacts avec pagination et filtres.

Paramètres de requête :

• page (integer) : Numéro de page - Défaut : 1
• per_page (integer) : Éléments par page (1-100) - Défaut : 12
• search (string) : Recherche textuelle
• status_filter (string) : Filtre par statut - Défaut : validation
• source_filter (string) : Filtre par source
• agent_filter (string) : ID hashé de l'agent
• targeting_filter (string) : ID hashé du ciblage
• sort_field (string) : Champ de tri - Défaut : created_at
• sort_direction (string) : Direction (asc/desc) - Défaut : desc
• include_emails (boolean) : Inclure les emails - Défaut : false
• semantic_search (boolean) : Recherche par IA - Défaut : false

Statuts disponibles :

• preparation : Leads en préparation
• validation : En attente de validation
• nurture : En nurturing actif
• won : Convertis en clients
• lost : Perdus
• later : À recontacter

Réponse :

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "firstname": "Jean",
            "lastname": "Dupont",
            "companyname": "TechCorp SAS",
            "job": "Directeur Marketing",
            "status": "nurture",
            "source": "linkedin",
            "contacts": [
                {
                    "type": "email",
                    "value": "jean.dupont@techcorp.com",
                    "verified": true
                }
            ],
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-20T14:45:00Z",
            "agent": {
                "id": "dEf456Zw",
                "firstname": "Pierre",
                "lastname": "Martin"
            },
            "agent_targeting": {
                "id": "gHi789Uv",
                "summary": "CMO Tech B2B France",
                "status": "active"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 12,
        "to": 12,
        "total": 58
    }
}

POST /api/contacts/manual

Ajoute des contacts manuellement via URLs LinkedIn.

Limites :

• Chaque agent a une limite de leads manuels basée sur le nombre de boîtes email
• 500 leads manuels par mois d'abonnement par boîte email
• Si la limite est atteinte, l'API retournera une erreur 409

Corps de la requête :

{
    "agent_id": "aBc123Xy",
    "urls": "https://linkedin.com/in/john-doe,https://linkedin.com/in/jane-smith"
}

Réponse :

{
    "success": true,
    "message": "Successfully processed 2 URLs",
    "created_count": 2,
    "duplicate_count": 0,
    "total_urls": 2,
    "errors": []
}

Réponse d'erreur (limite atteinte) :

{
    "success": false,
    "error": "Limite de leads manuels atteinte",
    "details": {
        "current": 3500,
        "limit": 3500,
        "remaining": 0,
        "requested": 5
    },
    "message": "Vous avez actuellement 3500 leads manuels sur une limite de 3500. Vous pouvez encore ajouter 0 lead(s)."
}

3. Statistiques

GET /api/agents/{agentId}/stats

Récupère les statistiques de performance d'un agent.

Paramètres :

• period : Période d'analyse (7d, 14d, 30d, 60d, 90d, 120d, 180d, 365d) - Par défaut : 14d
  • 7d : 7 jours
  • 14d : 14 jours
  • 30d : 30 jours
  • 60d : 60 jours
  • 90d : 90 jours
  • 120d : 120 jours
  • 180d : 180 jours
  • 365d : 365 jours

Réponse :

{
    "success": true,
    "agent": {
        "id": "aBc123Xy",
        "firstname": "Pierre",
        "lastname": "Martin"
    },
    "period": "30d",
    "stats": {
            "sent": {
                "current": 45,
                "previous": 38,
                "change": {
                    "value": 18.4,
                    "trend": "up",
                    "display": "+18.4%"
                },
                "label": "Messages envoyés"
            },
            "received": {
                "current": 32,
                "previous": 25,
                "change": {
                    "value": 28.0,
                    "trend": "up",
                    "display": "+28.0%"
                },
                "label": "Messages reçus"
            },
            "leads_won": {
                "current": 3,
                "previous": 2,
                "change": {
                    "value": 50.0,
                    "trend": "up",
                    "display": "+50.0%"
                },
                "label": "Leads gagnés"
            },
            "response_rate": {
                "current": 26.7,
                "label": "Taux de réponse (%)"
            },
            "lead_rate": {
                "current": 6.7,
                "label": "Taux de conversion (%)"
            },
            "relevance": {
                "current": 7.8,
                "label": "Pertinence moyenne"
            }
        }
    }
}

4. Emails

GET /api/emails

Récupère les emails de tous vos agents.

Paramètres :

• category (string) : Catégorie d'emails (optionnel - sans filtre par défaut)
• page (integer) : Numéro de page - Défaut : 1
• per_page (integer) : Éléments par page - Défaut : 25
• search (string) : Recherche textuelle
• semantic_search (boolean) : Recherche par IA - Défaut : false
• agent_filter (string) : ID hashé de l'agent (optionnel)

Catégories disponibles :

• received : Emails reçus
• sent : Emails envoyés
• to_handle : À traiter
• interested : Prospects intéressés
• not_interested : Non intéressés
• neutral : Neutres
• block : À bloquer
• auto_reply : Réponses automatiques
• antispam : Antispam
• unattributed : Non attribués

5. Blocklist

GET /api/blocklist

Récupère la liste de blocage.

Paramètres :

• type : Type de blocage (email, domain, all) - Défaut : all
• page : Numéro de page
• per_page : Éléments par page

Réponse :

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "type": "email",
            "value": "spam@example.com",
            "created_at": "2024-01-15T10:30:00Z"
        },
        {
            "id": "dEf456Zw",
            "type": "domain",
            "value": "spammer.com",
            "created_at": "2024-01-15T09:45:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "total": 25
    }
}

POST /api/blocklist

Ajoute un élément à bloquer.

Corps :

{
    "type": "email",
    "value": "unwanted@spam.com"
}

Types supportés :

• email : Adresse email complète
• domain : Nom de domaine

DELETE /api/blocklist

Supprime un élément de la blocklist par sa valeur.

Corps :

{
    "value": "unwanted@spam.com"
}

6. Gestion des Emails (Mailbox)

GET /api/emails/to-validate

Récupère la liste des emails de prise de contact en attente de validation.

Paramètres :

• page : Numéro de page - Défaut : 1
• per_page : Éléments par page (1-100) - Défaut : 12
• agent_filter : ID hashé de l'agent

Réponse :

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "type": "lead",
            "lead_name": "Jean Dupont",
            "company": "TechCorp",
            "email": "jean.dupont@techcorp.com",
            "agent": {
                "id": "dEf456Zw",
                "name": "Pierre Martin"
            },
            "subject": "Votre solution d'automatisation",
            "status": "pending_validation",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-15T10:30:00Z",
            "custom_messages": { ... },
            "has_custom_messages": true,
            "autovalidated_at": null,
            "actions": {
                "validate": "https://gustave.email/api/emails/validate/aBc123Xy",
                "reject": "https://gustave.email/api/emails/reject/aBc123Xy"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 12,
        "to": 12,
        "total": 58
    }
}

GET /api/emails/to-handle

Récupère la liste des réponses email en attente de traitement.

Paramètres :

• page : Numéro de page - Défaut : 1
• per_page : Éléments par page (1-100) - Défaut : 25
• agent_filter : ID hashé de l'agent

Réponse :

{
    "success": true,
    "data": [
        {
            "id": "gHi789Uv",
            "type": "email_received",
            "conversation_id": "conv_123",
            "lead_name": "Marie Durand",
            "company": "Innovation SA",
            "email": "marie@innovation.com",
            "agent": {
                "id": "dEf456Zw",
                "name": "Pierre Martin"
            },
            "subject": "Re: Votre proposition",
            "status": "to_handle",
            "received_at": "2024-01-20T14:45:00Z",
            "sentiment": "positive",
            "intent": "interested",
            "summary": "Le prospect souhaite plus d'informations",
            "relevance": 8.5,
            "answer": {
                "body": "Bonjour Marie, voici les informations...",
                "type": "ai_generated"
            },
            "actions": {
                "validate": "https://gustave.email/api/emails/validate-response/gHi789Uv",
                "skip": "https://gustave.email/api/emails/skip-response/gHi789Uv"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "per_page": 25,
        "to": 25,
        "total": 72
    }
}

POST /api/emails/validate/{leadId}

Valide une prise de contact email pour envoi automatique.

Corps :

{
    "custom_messages": {
        "subject": "Sujet personnalisé",
        "emails": [
            {
                "body": "Contenu personnalisé"
            }
        ]
    }
}

Réponse :

{
    "success": true,
    "message": "Lead validated successfully - will be sent automatically in 48h",
    "data": {
        "lead_id": "aBc123Xy",
        "validated_at": "2024-01-22T10:30:00Z",
        "auto_send_delay_hours": 48
    }
}

POST /api/emails/reject/{leadId}

Refuse une prise de contact email.

Réponse :

{
    "success": true,
    "message": "Lead rejected successfully - will be deleted automatically in 48h",
    "data": {
        "lead_id": "aBc123Xy",
        "unvalidated_at": "2024-01-22T10:30:00Z",
        "auto_delete_delay_hours": 48
    }
}

POST /api/emails/validate-response/{emailId}

Valide une réponse email avec possibilité de personnaliser le contenu.

Corps :

{
    "content": "Contenu personnalisé de la réponse (optionnel)",
    "cc": "manager@company.com"
}

Notes :

• Si content n'est pas fourni, la réponse AI existante sera utilisée
• Si cc est fourni, le lead sera automatiquement marqué comme gagné (transfert humain)

Réponse :

{
    "success": true,
    "message": "Email response saved successfully - waiting to be sent",
    "data": {
        "email_id": "gHi789Uv",
        "answer_status": "waiting",
        "cc_added": true
    }
}

POST /api/emails/skip-response/{emailId}

Marque une réponse email comme ignorée.

Réponse :

{
    "success": true,
    "message": "Email response skipped successfully",
    "data": {
        "email_id": "gHi789Uv",
        "answer_status": "skipped"
    }
}

7. Webhooks

POST /api/webhooks/subscribe

Souscrit à un événement webhook.

Corps :

{
    "event": "lead_ready_for_validation",
    "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "tool": "zapier",
    "secret": "optional-secret"
}

DELETE /api/webhooks/unsubscribe

Se désabonne d'un webhook.

Corps :

{
    "webhook_id": "uuid-subscription"
}

GET /api/webhooks

Liste les webhooks actifs.

GET /api/webhooks/events

Liste les événements disponibles.

GET /api/webhooks/sample/{eventType}

Obtient un exemple de payload pour un événement.

Événements Webhook

Les webhooks permettent de recevoir des notifications en temps réel des événements Gustave.

Configuration détaillée : Consultez les guides d'intégration spécifiques :

• Intégration Zapier
• Intégration Make
• Interface Gustave > Paramètres > Webhooks

Événements disponibles :

• lead_ready_for_validation : Lead prêt à être validé
• new_email_received : Nouvel email important reçu
• opportunity_transferred : Opportunité commerciale détectée
• lead_lost : Prospect perdu
• lead_blocked : Lead bloqué automatiquement
• reply_sent : Réponse envoyée à un prospect
• auto_reply_prepared : Réponse automatique préparée

Format général :

{
    "event": "event_name",
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "aBc123Xy",
    "data": {
        // Données spécifiques à l'événement
    }
}

Codes d'Erreur

• 200 : Succès
• 201 : Créé avec succès
• 400 : Requête invalide
• 401 : Non authentifié
• 403 : Permissions insuffisantes
• 404 : Ressource introuvable
• 409 : Conflit (duplication)
• 422 : Erreur de validation
• 429 : Trop de requêtes
• 500 : Erreur serveur
• 503 : Service temporairement indisponible

Limites de Taux

• 60 requêtes par minute par token
• 1000 requêtes par jour par utilisateur
• Recherche sémantique : 10 requêtes/minute
• Création de leads : 20 requêtes/minute

Les headers de réponse incluent :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Exemples d'Utilisation

cURL

# Récupérer les informations utilisateur
curl -H "Accept: application/json" \
     "https://gustave.email/api/me?api_key=votre-token"

# Récupérer des contacts
curl -H "Accept: application/json" \
     "https://gustave.email/api/contacts?api_key=votre-token&status_filter=nurture"

# Ajouter un contact
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"agent_id":"aBc123Xy","urls":"https://linkedin.com/in/prospect"}' \
     "https://gustave.email/api/contacts/manual?api_key=votre-token"

JavaScript

const API_TOKEN = 'votre-token';
const BASE_URL = 'https://gustave.email/api';

// Récupérer les informations utilisateur
async function getMe() {
    const response = await fetch(`${BASE_URL}/me?api_key=${API_TOKEN}`, {
        headers: {
            'Accept': 'application/json'
        }
    });
    
    return response.json();
}

// Récupérer des contacts
async function getContacts() {
    const response = await fetch(`${BASE_URL}/contacts?api_key=${API_TOKEN}&status_filter=nurture`, {
        headers: {
            'Accept': 'application/json'
        }
    });
    
    return response.json();
}

// Ajouter des contacts
async function addContacts(agentId, urls) {
    const response = await fetch(`${BASE_URL}/contacts/manual?api_key=${API_TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ agent_id: agentId, urls })
    });
    
    return response.json();
}

Python

import requests

API_TOKEN = 'votre-token'
BASE_URL = 'https://gustave.email/api'

headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    'Accept': 'application/json'
}

# Récupérer les informations utilisateur
response = requests.get(f'{BASE_URL}/me?api_key={API_TOKEN}')
user_info = response.json()

# Récupérer des contacts
response = requests.get(
    f'{BASE_URL}/contacts?api_key={API_TOKEN}',
    params={'status_filter': 'nurture'}
)
contacts = response.json()

# Récupérer la blocklist (tous types)
response = requests.get(f'{BASE_URL}/blocklist?api_key={API_TOKEN}&type=all')
blocklist = response.json()

# Supprimer de la blocklist
response = requests.delete(
    f'{BASE_URL}/blocklist?api_key={API_TOKEN}',
    json={'value': 'spam@example.com'}
)

# Statistiques d'un agent
response = requests.get(
    f'{BASE_URL}/agents/aBc123Xy/stats?api_key={API_TOKEN}',
    params={'period': '30d'}
)
stats = response.json()

PHP

<?php
$apiToken = 'votre-token';
$baseUrl = 'https://gustave.email/api';

$headers = [
    'Authorization: Bearer ' . $apiToken,
    'Accept: application/json',
    'Content-Type: application/json'
];

// Récupérer les informations utilisateur
function getMe($baseUrl, $apiToken) {
    $ch = curl_init($baseUrl . '/me?api_key=' . $apiToken);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Récupérer des contacts
function getContacts($baseUrl, $apiToken) {
    $ch = curl_init($baseUrl . '/contacts?api_key=' . $apiToken . '&status_filter=nurture');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Ajouter des contacts
function addContacts($baseUrl, $apiToken, $agentId, $urls) {
    $data = json_encode([
        'agent_id' => $agentId,
        'urls' => $urls
    ]);
    
    $ch = curl_init($baseUrl . '/contacts/manual?api_key=' . $apiToken);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Utilisation
$userInfo = getMe($baseUrl, $apiToken);
$contacts = getContacts($baseUrl, $apiToken);
$result = addContacts($baseUrl, $apiToken, 'aBc123Xy', 'https://linkedin.com/in/prospect');

// Avec Guzzle (plus moderne)
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://gustave.email/api/',
    'headers' => [
        'Accept' => 'application/json'
    ]
]);

// Récupérer les informations utilisateur
$response = $client->get('me', [
    'query' => ['api_key' => $apiToken]
]);
$userInfo = json_decode($response->getBody(), true);

// Récupérer des contacts
$response = $client->get('contacts', [
    'query' => ['api_key' => $apiToken, 'status_filter' => 'nurture']
]);
$contacts = json_decode($response->getBody(), true);

// Ajouter des contacts
$response = $client->post('contacts/manual', [
    'query' => ['api_key' => $apiToken],
    'json' => [
        'agent_id' => 'aBc123Xy',
        'urls' => 'https://linkedin.com/in/prospect'
    ]
]);
$result = json_decode($response->getBody(), true);
?>