Documentation API Manuscry

Introduction

L'API Manuscry permet d'ajouter des contacts à vos campagnes de courriers personnalisés de manière programmatique. Cette API vous permet d'intégrer facilement l'ajout de contacts dans vos workflows existants.

Rate Limiting :

L'API est limitée à 100 requêtes par minute par utilisateur pour garantir la stabilité du service.

Limitations importantes :

Les campagnes en pause (status: paused) peuvent être consultées via l'API mais aucune action d'écriture n'est autorisée. Ces actions retourneront une erreur HTTP 403 avec le message "Campaign paused".

Les campagnes annulées (status: cancelled) peuvent être consultées via l'API mais aucune action d'écriture n'est autorisée (ajout de contacts, validation de courriers, etc.). Ces actions retourneront une erreur HTTP 403 avec le message "Campaign cancelled".

Terminologie et compatibilité :

Manuscry utilise le terme "campaign" (campagne) dans toute son API pour désigner une campagne de courriers.

Par compatibilité technique, l'alias agent_filter est également accepté mais campaign_filter est recommandé.

Si les deux paramètres sont fournis, campaign_filter est prioritaire.

Authentification

L'API utilise l'authentification par clé API. Vous devez créer une clé API depuis votre espace utilisateur, et l'utiliser dans vos requêtes d'une des façons suivantes.

Header Authorization : Authorization: Bearer YOUR_API_KEY

Paramètre URL : ?api_key=YOUR_API_KEY

Pour créer une clé API, rendez-vous sur votre espace puis dans la section "API", créez votre clé, et copiez la (elle ne sera affichée qu'une fois). Gardez votre clé API confidentielle et ne la partagez jamais publiquement.

Serveur MCP (Model Context Protocol)

Branchez votre compte Manuscry à n'importe quel client compatible MCP (claude.ai, Claude Desktop, Cursor, Claude Code) pour interagir conversationnellement avec vos campagnes, contacts et courriers. Le serveur est accessible sur mcp.manuscry.com avec votre token API habituel.

Authentification :

Le token est le même que pour l'API REST : générez-le depuis votre espace utilisateur, section « API ». Deux façons de le fournir :

Header Authorization: Bearer <votre-token> (recommandé)

Paramètre d'URL ?api_key=<votre-token> - pour les clients qui ne permettent pas de configurer de headers

Configuration client (exemple Claude Desktop / Claude Code) :

Dans le fichier de configuration de votre client (mcpServers), ajoutez une entrée nommée manuscry avec :

type : http

url : https://mcp.manuscry.com/mcp

headers : Authorization: Bearer sk_votre_token... (votre token API généré depuis l'espace utilisateur)

Configuration claude.ai (connecteur personnalisé) :

Paramètres > Connecteurs > Ajouter un connecteur personnalisé, avec comme URL : https://mcp.manuscry.com/mcp?api_key=sk_votre_token...

Limitations :

Rate-limit 100 req/min partagé avec l'API REST.

Token = accès complet (pas de scopes en MVP).

Le token Manuscry n'est utilisable que sur mcp.manuscry.com (et inversement pour Meetlane).

Outils disponibles (18) :

add_contact_to_campaign - Ajoute un contact à une campagne (déclenche le workflow d'envoi de courrier).

add_to_blocklist - Ajoute une entrée à la blocklist (email, domain, company, siren, address).

block_contact - Bloque un contact et annule ses contenus en attente.

find_postal_address - Lance une recherche d'adresse postale.

get_account_info - Récupère les infos du compte.

get_campaign_details - Détails d'une campagne.

get_campaign_stats - Statistiques d'une campagne (period: 7d/30d/90d/365d).

get_postal_address_results - Récupère les résultats d'une recherche d'adresse postale.

list_blocklist - Liste la blocklist.

list_calendar_events - Événements calendrier (anniversaires, envois planifiés).

list_campaigns - Liste les campagnes.

list_contacts - Liste les contacts avec filtres.

list_letters - Liste des courriers avec filtres.

list_letters_to_validate - Courriers en attente de validation.

mark_letter_as_printed - Marque un courrier comme imprimé (mode self-print uniquement).

reject_letter - Annule définitivement un courrier.

remove_from_blocklist - Retire une entrée de la blocklist.

validate_letter - Valide un courrier (délai 60 min avant production).

Récupérer la configuration d'une campagne

Récupère les champs personnalisés et la configuration d'une campagne spécifique. Les champs retournés dépendent du type de campagne et de la configuration de la lettre.

GET


                                                https://manuscry.com/api/campaigns/{campaign_id}/settings

Paramètres

Nom	Type	Requis	Description
campaign_id	string	Oui	ID hashé de la campagne (visible dans l'URL de votre campagne)

Exemple de requête

curl -X GET "https://manuscry.com/api/campaigns/{campaign_id}/settings" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/campaigns/{campaign_id}/settings', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaign_id}/settings');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "linkedin_manual": {
        "success": true,
        "data": {
            "campaign": {
                "id": "abc123def456",
                "name": "Ma campagne LinkedIn",
                "type": "linkedin",
                "status": "active",
                "site": "manuscry",
                "can_add_contacts": true,
                "contacts_count": 25
            },
            "fields": [
                {
                    "key": "identifier",
                    "label": "Identifiant unique",
                    "type": "text",
                    "required": false,
                    "validation": "nullable|string|max:100",
                    "placeholder": "Généré automatiquement si vide",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "system"
                },
                {
                    "key": "linkedin_url",
                    "label": "URL LinkedIn",
                    "type": "url",
                    "required": true,
                    "validation": "required|url|regex:/linkedin\\.com\\/in\\/.+/",
                    "placeholder": "https://www.linkedin.com/in/nom-prenom/",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "ai_context",
                    "label": "Contexte personnel (optionnel)",
                    "type": "textarea",
                    "required": false,
                    "validation": "nullable|string|max:500",
                    "placeholder": "Informations spécifiques non présentes sur le profil...",
                    "is_custom": false,
                    "is_in_letter": true,
                    "validation_type": "optional"
                }
            ],
            "sheet_type": "linkedin_urls"
        }
    },
    "manual_with_variables": {
        "success": true,
        "data": {
            "campaign": {
                "id": "def456ghi789",
                "name": "Prospection dirigeants",
                "type": "manual",
                "status": "active",
                "site": "manuscry",
                "can_add_contacts": true,
                "contacts_count": 150
            },
            "fields": [
                {
                    "key": "identifier",
                    "label": "Identifiant unique",
                    "type": "text",
                    "required": false,
                    "validation": "nullable|string|max:100",
                    "placeholder": "Généré automatiquement si vide",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "system"
                },
                {
                    "key": "address_line1",
                    "label": "Adresse ligne 1",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:255",
                    "placeholder": "Nom ou raison sociale",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "address_line2",
                    "label": "Adresse ligne 2",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:255",
                    "placeholder": "Numéro et nom de rue",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "address_zip",
                    "label": "Code postal",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:20",
                    "placeholder": "75001",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "address_city",
                    "label": "Ville",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:255",
                    "placeholder": "PARIS",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "address_country",
                    "label": "Pays",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:2",
                    "placeholder": "FR",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "secteur_activite",
                    "label": "Secteur d'activité",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:255",
                    "placeholder": "Exemple: Finance, Tech, Santé...",
                    "is_custom": true,
                    "is_in_letter": true,
                    "validation_type": "required"
                }
            ],
            "sheet_type": "manual_contacts"
        }
    },
    "birthday": {
        "success": true,
        "data": {
            "campaign": {
                "id": "jkl012mno345",
                "name": "Anniversaires clients",
                "type": "birthday",
                "status": "active",
                "site": "manuscry",
                "can_add_contacts": true,
                "contacts_count": 89
            },
            "fields": [
                {
                    "key": "identifier",
                    "label": "Identifiant unique",
                    "type": "text",
                    "required": false,
                    "validation": "nullable|string|max:100",
                    "placeholder": "Généré automatiquement si vide",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "system"
                },
                {
                    "key": "birthday_date",
                    "label": "Date d'anniversaire",
                    "type": "date",
                    "required": true,
                    "validation": "required|date|date_format:Y-m-d",
                    "placeholder": "1985-03-15",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "address_line1",
                    "label": "Adresse ligne 1",
                    "type": "text",
                    "required": true,
                    "validation": "required|string|max:255",
                    "placeholder": "Nom complet",
                    "is_custom": false,
                    "is_in_letter": false,
                    "validation_type": "required"
                },
                {
                    "key": "ai_context",
                    "label": "Contexte personnel (optionnel)",
                    "type": "textarea",
                    "required": false,
                    "validation": "nullable|string|max:500",
                    "placeholder": "Informations sur le client...",
                    "is_custom": false,
                    "is_in_letter": true,
                    "validation_type": "optional"
                }
            ],
            "sheet_type": "birthday_contacts"
        }
    },
    "linkedin_auto": {
        "success": true,
        "data": {
            "campaign": {
                "id": "pqr678stu901",
                "name": "Ciblage LinkedIn automatique",
                "type": "linkedin",
                "status": "active",
                "site": "manuscry",
                "can_add_contacts": false,
                "contacts_count": 0
            },
            "fields": [],
            "sheet_type": null
        }
    }
}

Champs dynamiques :

Les champs retournés dépendent de plusieurs facteurs :

Type de campagne : manual, birthday, linkedin, self-print

Configuration de la lettre : Variables {custom} détectées dans le contenu

Mode de personnalisation : IA complète (ai_context) ou texte à trous (variables)

Utilité pour la validation :

Cet endpoint est essentiel avant d'ajouter des contacts. La structure de validation_errors retournée lors d'un échec vous permet de savoir exactement quels champs sont manquants (missing_fields) ou invalides (invalid_fields).

Champ can_add_contacts :

Ce champ indique si la campagne accepte l'ajout manuel de contacts via API.

true : Vous pouvez ajouter des contacts (manual, birthday, linkedin manuel, self-print)

false : Ajout manuel interdit (linkedin auto, bases de données automatiques)

Campagnes avec ciblage automatique :

Les campagnes avec ciblage automatique retournent can_add_contacts: false et fields: [].

Ces campagnes génèrent leurs contacts automatiquement selon les critères de ciblage configurés.

Champ ai_context :

Présent uniquement si le contenu principal de la lettre est en mode IA (génération complète).

Ce champ est toujours optionnel et permet de fournir un contexte personnalisé qui sera fusionné avec :

Pour LinkedIn : le contexte extrait automatiquement du profil

Pour les autres types : le contexte général de la campagne

Variables personnalisées :

Si votre lettre contient des variables {custom} (exemple: {secteur_activite}, {chiffre_affaires}),

un champ sera généré pour chaque variable avec :

is_custom: true

is_in_letter: true

required: true (car utilisé dans la lettre)

Utilisation recommandée :

Appelez cet endpoint AVANT d'ajouter des contacts pour :

Vérifier que can_add_contacts est à true

Récupérer la liste exacte des champs requis

Connaître les validations à appliquer

Comprendre quels champs sont utilisés dans la lettre (is_in_letter: true)

Statistiques d'une campagne

Récupère les statistiques de performance d'une campagne.

GET


                                                https://manuscry.com/api/campaigns/{campaignId}/stats

Paramètres

Nom	Type	Requis	Description
campaignId	string	Oui	ID hashé de la campagne
period	string	Non	Période d'analyse (7d, 14d, 30d, 60d, 90d, 120d, 180d, 365d)

Exemple de requête

curl -X GET "https://manuscry.com/api/campaigns/{campaignId}/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/campaigns/{campaignId}/stats', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaignId}/stats');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "campaign": {
        "id": "aBc123Xy",
        "name": "Campagne Printemps 2024"
    },
    "period": "30d",
    "stats": {
        "letters_sent": {
            "current": 45,
            "previous": 38,
            "change": {
                "value": 18.4,
                "trend": "up",
                "display": "+18.4%"
            },
            "label": "Courriers envoyés"
        },
        "qr_scanned": {
            "current": 32,
            "previous": 25,
            "change": {
                "value": 28,
                "trend": "up",
                "display": "+28.0%"
            },
            "label": "QR codes flashés"
        },
        "qr_scan_rate": {
            "current": 71.1,
            "label": "Taux de flash (%)"
        },
        "letters_returned": {
            "current": 3,
            "label": "Courriers retournés"
        },
        "return_rate": {
            "current": 6.7,
            "label": "Taux de retour (%)"
        }
    }
}

Endpoints disponibles:

/api/campaigns/{campaignId}/stats (recommandé pour Manuscry)

/api/agents/{campaignId}/stats (alias fonctionnel pour compatibilité)

Envoyer un courrier (ajout manuel)

Envoie un courrier à un destinataire en l'ajoutant à une campagne en mode ajout manuel ou intégration. Le contact est enregistré dans la campagne puis le courrier est généré et envoyé selon sa configuration. À utiliser pour brancher Manuscry à votre CRM, vos formulaires ou tout autre outil tiers.

POST


                                                https://manuscry.com/api/campaigns/{campaign_id}/contacts

Paramètres

Nom	Type	Requis	Description
campaign_id	string	Oui	ID hashé de la campagne (type: manual)

Exemple de requête

curl -X POST "https://manuscry.com/api/campaigns/{campaign_id}/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "contact_unique_001",
    "address_line1": "Jean Dupont",
    "address_line2": "12 rue de la Paix",
    "address_line3": "Bâtiment A",
    "address_zip": "75001",
    "address_city": "PARIS",
    "address_country": "FR",
    "scheduled_at": "2025-12-25",
    "ai_context": "Dirigeant d'une startup fintech parisienne, passionné par l'innovation"
}'

const response = await fetch('https://manuscry.com/api/campaigns/{campaign_id}/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "identifier": "contact_unique_001",
      "address_line1": "Jean Dupont",
      "address_line2": "12 rue de la Paix",
      "address_line3": "Bâtiment A",
      "address_zip": "75001",
      "address_city": "PARIS",
      "address_country": "FR",
      "scheduled_at": "2025-12-25",
      "ai_context": "Dirigeant d'une startup fintech parisienne, passionné par l'innovation"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaign_id}/contacts');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "identifier": "contact_unique_001",
    "address_line1": "Jean Dupont",
    "address_line2": "12 rue de la Paix",
    "address_line3": "Bâtiment A",
    "address_zip": "75001",
    "address_city": "PARIS",
    "address_country": "FR",
    "scheduled_at": "2025-12-25",
    "ai_context": "Dirigeant d\'une startup fintech parisienne, passionné par l\'innovation"
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Contact added successfully",
    "data": {
        "contact": {
            "identifier": "contact_unique_001",
            "fields": {
                "identifier": "contact_unique_001",
                "address_line1": "Jean Dupont",
                "address_line2": "12 rue de la Paix",
                "address_line3": "Bâtiment A",
                "address_zip": "75001",
                "address_city": "PARIS",
                "address_country": "FR",
                "scheduled_at": "2025-12-25",
                "ai_context": "Dirigeant d'une startup fintech parisienne, passionné par l'innovation"
            },
            "created_at": "2025-11-02T10:30:00.000000Z",
            "updated_at": "2025-11-02T10:30:00.000000Z"
        },
        "campaign": {
            "id": "abc123def456",
            "contacts_count": 26
        }
    }
}

Type de campagne : manual

Champs obligatoires :

address_line1 : Nom ou raison sociale du destinataire

address_line2 : Numéro et nom de rue

address_zip : Code postal

address_city : Ville (en majuscules)

address_country : Code pays ISO 3166-1 alpha-2 (FR, BE, CH, etc.)

Champs optionnels :

identifier : Identifiant unique (auto-généré si vide)

address_line3 : Complément d'adresse (étage, appartement, etc.)

scheduled_at : Date d'envoi programmée au format YYYY-MM-DD (optionnel)

ai_context : Contexte personnalisé pour la génération IA (si mode IA activé)

Variables personnalisées : Si votre lettre contient {nom_variable}, ajoutez le champ correspondant

Gestion des erreurs de validation :

En cas d'erreur de validation (HTTP 422), la réponse inclut trois clés pour faciliter le debugging :

validation_errors : objet avec chaque champ en erreur et son message explicite (ex. address_zip: "Le champ Code postal est obligatoire")

missing_fields : tableau des champs obligatoires manquants

invalid_fields : tableau des champs présents mais invalides (format incorrect, etc.)

Programmation d'envoi :

Le paramètre scheduled_at permet de programmer l'envoi à une date spécifique (format: YYYY-MM-DD).

Si fourni, cette date est prioritaire sur agent.min_scheduled_date.

Dates passées acceptées (envoi immédiat si date passée).

Champs dynamiques :

Les champs requis dépendent de la configuration de votre lettre. Utilisez GET /api/campaigns/{campaign_id}/settings pour récupérer la liste complète des champs avec leurs validations.

Champ ai_context :

Le champ ai_context est optionnel. Si le contenu principal de votre lettre est en mode IA, ce champ permet de fournir un contexte personnalisé qui sera utilisé pour personnaliser le contenu généré automatiquement.

Variables personnalisées :

Si votre lettre contient des variables {custom} (par exemple {secteur_activite}), vous devez inclure les champs correspondants dans la requête (secteur_activite dans cet exemple).

Programmer une carte d'anniversaire

Programme l'envoi d'une carte d'anniversaire en ajoutant un contact (avec date de naissance) à une campagne de type anniversaire. La carte est générée et envoyée automatiquement 5 jours avant la date (10 jours pour l'international). À utiliser pour brancher Manuscry à votre CRM ou tout outil d'intégration.

POST


                                                https://manuscry.com/api/campaigns/{campaign_id}/contacts

Paramètres

Nom	Type	Requis	Description
campaign_id	string	Oui	ID hashé de la campagne (type: birthday)

Exemple de requête

curl -X POST "https://manuscry.com/api/campaigns/{campaign_id}/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "contact_unique_002",
    "birthday_date": "1985-03-15",
    "address_line1": "Marie Martin",
    "address_line2": "456 avenue des Champs",
    "address_zip": "69001",
    "address_city": "LYON",
    "address_country": "FR",
    "ai_context": "Cliente fidèle depuis 3 ans, apprécie nos services premium"
}'

const response = await fetch('https://manuscry.com/api/campaigns/{campaign_id}/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "identifier": "contact_unique_002",
      "birthday_date": "1985-03-15",
      "address_line1": "Marie Martin",
      "address_line2": "456 avenue des Champs",
      "address_zip": "69001",
      "address_city": "LYON",
      "address_country": "FR",
      "ai_context": "Cliente fidèle depuis 3 ans, apprécie nos services premium"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaign_id}/contacts');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "identifier": "contact_unique_002",
    "birthday_date": "1985-03-15",
    "address_line1": "Marie Martin",
    "address_line2": "456 avenue des Champs",
    "address_zip": "69001",
    "address_city": "LYON",
    "address_country": "FR",
    "ai_context": "Cliente fidèle depuis 3 ans, apprécie nos services premium"
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Contact added successfully",
    "data": {
        "contact": {
            "identifier": "contact_unique_002",
            "fields": {
                "identifier": "contact_unique_002",
                "birthday_date": "1985-03-15",
                "address_line1": "Marie Martin",
                "address_line2": "456 avenue des Champs",
                "address_zip": "69001",
                "address_city": "LYON",
                "address_country": "FR",
                "ai_context": "Cliente fidèle depuis 3 ans, apprécie nos services premium"
            },
            "created_at": "2025-11-02T10:30:00.000000Z",
            "updated_at": "2025-11-02T10:30:00.000000Z"
        },
        "campaign": {
            "id": "xyz789abc123",
            "contacts_count": 15
        }
    }
}

Type de campagne : birthday

Champs obligatoires :

birthday_date : Date d'anniversaire au format YYYY-MM-DD (exemple: 1985-03-15)

address_line1 : Nom du destinataire

address_line2 : Numéro et nom de rue

address_zip : Code postal

address_city : Ville (en majuscules)

address_country : Code pays ISO 3166-1 alpha-2 (FR, BE, CH, etc.)

Champs optionnels :

identifier : Identifiant unique (auto-généré si vide)

address_line3 : Complément d'adresse

ai_context : Contexte personnalisé pour la génération IA (si mode IA activé)

Variables personnalisées selon la configuration de votre lettre

Envoi automatique :

Les cartes d'anniversaire sont envoyées automatiquement 5 jours avant la date pour la France, 10 jours avant pour l'international.

Format de date :

La date doit être au format ISO 8601 (YYYY-MM-DD). Exemples valides : 1985-03-15, 1990-12-25.

Champs dynamiques :

Utilisez GET /api/campaigns/{campaign_id}/settings pour récupérer la liste complète des champs requis selon votre configuration de lettre.

Gestion des erreurs de validation :

En cas d'erreur (HTTP 422), la réponse détaille précisément les problèmes avec chaque champ manquant ou invalide pour faciliter le debugging.

Envoyer un courrier à partir d'un profil LinkedIn

Envoie un courrier à un contact identifié par son URL LinkedIn, en l'ajoutant à une campagne LinkedIn en mode ajout manuel ou intégration. Manuscry enrichit le profil (parcours, entreprise) et recherche l'adresse postale automatiquement avant de générer le courrier. À utiliser pour brancher Manuscry à votre CRM ou à un workflow d'enrichissement.

POST


                                                https://manuscry.com/api/campaigns/{campaign_id}/contacts

Paramètres

Nom	Type	Requis	Description
campaign_id	string	Oui	ID hashé de la campagne (type: linkedin en mode manuel uniquement)

Exemple de requête

curl -X POST "https://manuscry.com/api/campaigns/{campaign_id}/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "contact_unique_003",
    "linkedin_url": "https://www.linkedin.com/in/jean-dupont-marketing",
    "ai_context": "Rencontré lors de la conférence SaaS 2024, intéressé par nos solutions d'automatisation"
}'

const response = await fetch('https://manuscry.com/api/campaigns/{campaign_id}/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "identifier": "contact_unique_003",
      "linkedin_url": "https://www.linkedin.com/in/jean-dupont-marketing",
      "ai_context": "Rencontré lors de la conférence SaaS 2024, intéressé par nos solutions d'automatisation"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaign_id}/contacts');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "identifier": "contact_unique_003",
    "linkedin_url": "https://www.linkedin.com/in/jean-dupont-marketing",
    "ai_context": "Rencontré lors de la conférence SaaS 2024, intéressé par nos solutions d\'automatisation"
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Contact added successfully",
    "data": {
        "contact": {
            "identifier": "contact_unique_003",
            "fields": {
                "identifier": "contact_unique_003",
                "linkedin_url": "https://www.linkedin.com/in/jean-dupont-marketing",
                "ai_context": "Rencontré lors de la conférence SaaS 2024, intéressé par nos solutions d'automatisation"
            },
            "created_at": "2025-11-02T10:30:00.000000Z",
            "updated_at": "2025-11-02T10:30:00.000000Z"
        },
        "campaign": {
            "id": "def456ghi789",
            "contacts_count": 42
        }
    }
}

Type de campagne : linkedin en mode manuel uniquement

Limitation importante :

Les campagnes LinkedIn avec ciblage automatique (leads_sub_source_type = linkedin_auto) ne supportent PAS l'ajout manuel.

Seules les campagnes LinkedIn en mode manuel (leads_sub_source_type = linkedin_manual) acceptent l'ajout de contacts via API.

Utilisez GET /api/campaigns/{campaign_id}/settings et vérifiez que can_add_contacts est à true avant d'ajouter un contact.

Champs obligatoires :

linkedin_url : URL complète du profil LinkedIn (format: https://www.linkedin.com/in/nom-prenom)

Champs optionnels :

identifier : Identifiant unique (auto-généré si vide)

ai_context : Contexte personnalisé complémentaire

Champ ai_context - Utilisation recommandée :

Le champ ai_context est optionnel mais recommandé. Il permet d'ajouter des informations spécifiques qui ne sont pas disponibles sur le profil LinkedIn public :

Contexte de rencontre (événement, conférence, recommandation)

Intérêts spécifiques exprimés lors d'échanges

Informations complémentaires sur les besoins

Ce contexte sera fusionné avec les informations extraites automatiquement du profil LinkedIn (parcours, expériences, compétences, entreprise actuelle).

Traitement asynchrone :

Le contact est d'abord ajouté au sheet, puis traité automatiquement toutes les 30 minutes par la commande all:leads-create-from-linkedin-manual-sheets qui :

Récupère les informations du profil LinkedIn

Recherche l'adresse postale

Crée le lead enrichi

Génère le courrier personnalisé

Le délai entre l'ajout via API et la génération du courrier peut donc être de 30 minutes maximum.

Gestion des erreurs de validation :

En cas d'erreur (HTTP 422), la réponse inclut validation_errors (messages détaillés), missing_fields (champs manquants) et invalid_fields (champs au format incorrect).

Générer un courrier en impression autonome

Génère un courrier prêt à imprimer (PNG haute définition) en ajoutant un contact à une campagne en mode impression autonome. Pas d'envoi postal - vous récupérez ensuite les fichiers via l'API pour les imprimer vous-même. À utiliser pour brancher Manuscry à votre CRM ou intégration.

POST


                                                https://manuscry.com/api/campaigns/{campaign_id}/contacts

Paramètres

Nom	Type	Requis	Description
campaign_id	string	Oui	ID hashé de la campagne (self-print)

Exemple de requête

curl -X POST "https://manuscry.com/api/campaigns/{campaign_id}/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "contact_unique_004",
    "address_line1": "Sophie Bernard",
    "address_line2": "789 boulevard Victor Hugo",
    "address_zip": "33000",
    "address_city": "BORDEAUX",
    "address_country": "FR",
    "ai_context": "Prospect qualifié lors du salon professionnel, secteur viticole"
}'

const response = await fetch('https://manuscry.com/api/campaigns/{campaign_id}/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "identifier": "contact_unique_004",
      "address_line1": "Sophie Bernard",
      "address_line2": "789 boulevard Victor Hugo",
      "address_zip": "33000",
      "address_city": "BORDEAUX",
      "address_country": "FR",
      "ai_context": "Prospect qualifié lors du salon professionnel, secteur viticole"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaign_id}/contacts');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "identifier": "contact_unique_004",
    "address_line1": "Sophie Bernard",
    "address_line2": "789 boulevard Victor Hugo",
    "address_zip": "33000",
    "address_city": "BORDEAUX",
    "address_country": "FR",
    "ai_context": "Prospect qualifié lors du salon professionnel, secteur viticole"
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Contact added successfully",
    "data": {
        "contact": {
            "identifier": "contact_unique_004",
            "fields": {
                "identifier": "contact_unique_004",
                "address_line1": "Sophie Bernard",
                "address_line2": "789 boulevard Victor Hugo",
                "address_zip": "33000",
                "address_city": "BORDEAUX",
                "address_country": "FR",
                "ai_context": "Prospect qualifié lors du salon professionnel, secteur viticole"
            },
            "created_at": "2025-11-02T10:30:00.000000Z",
            "updated_at": "2025-11-02T10:30:00.000000Z"
        },
        "campaign": {
            "id": "jkl012mno345",
            "contacts_count": 8
        }
    }
}

Type de campagne : Campagne en mode impression autonome (self-print)

Fonctionnement :

Les campagnes en impression autonome permettent de générer les fichiers haute définition des cartes sans envoi postal.

Vous récupérez les fichiers PNG haute résolution via l'API pour les imprimer vous-même.

Champs obligatoires :

Identiques aux contacts manuels :

address_line1 : Nom du destinataire

address_line2 : Numéro et nom de rue

address_zip : Code postal

address_city : Ville

address_country : Code pays ISO

Champs optionnels :

identifier : Identifiant unique (auto-généré si vide)

address_line3 : Complément d'adresse

ai_context : Contexte pour personnalisation IA

Variables personnalisées selon votre configuration

Limitation programmation :

Les campagnes self-print ne supportent PAS le paramètre scheduled_at.

Les fichiers sont générés et disponibles immédiatement après validation.

Pour des envois programmés, utilisez une campagne manuelle standard.

Récupération des fichiers :

Une fois le courrier généré, utilisez GET /api/letters?campaign_filter={campaign_id}&category=delivered pour récupérer les URLs des fichiers haute définition.

Les fichiers sont accessibles dans campaign.print_files de chaque lettre.

Formats supportés : a6, a6-vertical, a5, a5-vertical, a4, dl, dl-vertical (les formats publics sont a6, dl, a5 et a4 ; les variantes verticales a6-vertical, a5-vertical et dl-vertical restent réservées à l'admin).

Dimensions : selon le format de la campagne, ex. A6 (2400x1702px / 148x105mm) ou A4 (2400x3394px / 210x297mm).

Marquage impression :

Après avoir téléchargé et imprimé un courrier, utilisez POST /api/letters/mark-printed/{letterId} pour le marquer comme imprimé dans votre suivi.

Gestion des erreurs de validation :

En cas d'erreur (HTTP 422), la réponse inclut validation_errors (messages détaillés), missing_fields (champs manquants) et invalid_fields (champs au format incorrect).

Informations utilisateur

Récupère les informations de l'utilisateur connecté et la liste de ses campagnes (hors brouillons).

GET


                                                https://manuscry.com/api/me

Exemple de requête

curl -X GET "https://manuscry.com/api/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/me', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/me');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "user": {
        "id": "aBc123Xy",
        "name": "Marie Dupont",
        "email": "marie.dupont@example.com",
        "created_at": "2024-01-15T10:30:00.000000Z"
    },
    "campaigns": [
        {
            "id": "dEf456Zw",
            "name": "Campagne Printemps 2024",
            "status": "active",
            "internal_note": "Dirigeants tech",
            "is_active": true,
            "is_self_print": false
        },
        {
            "id": "gHi789Uv",
            "name": "Anniversaires Clients",
            "status": "active",
            "internal_note": null,
            "is_active": true,
            "is_self_print": true
        }
    ],
    "meta": {
        "total_campaigns": 2,
        "active_campaigns": 2
    }
}

Campagnes retournées :

Seules les campagnes publiées sont retournées (status != draft)

Les brouillons ne sont pas inclus dans les résultats

Champs des campagnes :

is_active : true si status = "active"

is_self_print : true si la campagne est en mode impression autonome

Statuts de campagne disponibles :

setup : Campagne en cours de configuration

active : Campagne active et opérationnelle

paused : Campagne en pause

cancelled : Campagne annulée (terminal)

pending_payment : Campagne en attente de paiement

Liste des contacts

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

GET


                                                https://manuscry.com/api/contacts

Paramètres

Nom	Type	Requis	Description
page	integer	Non	Numéro de page
per_page	integer	Non	Éléments par page (1-100)
search	string	Non	Recherche textuelle
status_filter	string	Non	Filtre par statut
source_filter	string	Non	Filtre par source
campaign_filter	string	Non	ID hashé de la campagne (recommandé - alias agent_filter accepté)
sort_field	string	Non	Champ de tri
sort_direction	string	Non	Direction (asc/desc)
semantic_search	boolean	Non	Recherche par IA

Exemple de requête

curl -X GET "https://manuscry.com/api/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/contacts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/contacts');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "firstname": "Jean",
            "lastname": "Dupont",
            "companyname": "TechCorp SAS",
            "status": "contact",
            "source": "linkedin_auto",
            "relevance": 8,
            "linkedin_url": "https://linkedin.com/in/jean-dupont",
            "picture": "https://example.com/avatar.jpg",
            "contacts": [
                {
                    "type": "postal",
                    "line1": "Jean Dupont",
                    "line2": "123 rue de Rivoli",
                    "zip": "75001",
                    "city": "Paris"
                }
            ],
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-20T14:45:00.000000Z",
            "campaign": {
                "id": "dEf456Zw",
                "name": "Campagne Printemps 2024"
            },
            "agent_targeting": null
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 12,
        "to": 12,
        "total": 58
    },
    "filters_applied": {
        "search": "TechCorp",
        "status_filter": "contact",
        "source_filter": null,
        "campaign_filter": null,
        "sort_field": "created_at",
        "sort_direction": "desc",
        "semantic_search": false
    }
}

Statuts disponibles :

enrich : Contacts en enrichissement

neutral : Contacts neutralisés (post-enrichissement sans match)

contact : Contacts enrichis, prêts pour génération

validation : En attente de validation utilisateur

nurture : Validé et programmé pour envoi

won : Conversion réussie (terminal positif)

lost : Lead perdu (terminal)

later : Reporté à plus tard

noanswer : Pas de réponse

error : Erreur technique (transitoire)

block : Bloqué (terminal, RGPD/blocklist)

cancelled : Annulé

Champs additionnels :

relevance : Score de pertinence (entier 1-10, null tant que non scoré)

linkedin_url : URL du profil LinkedIn (nullable)

picture : URL de la photo de profil (nullable)

Propriétés de touchpoints :

has_touchpoint_letter : Courrier livré au contact (boolean)

has_touchpoint_letter_flash : QR code flashé par le contact (boolean)

has_returned_letter : Courrier retourné (NPAI/PND) (boolean)

Bloquer un contact

Bloque un contact et tous ses doublons, annule les contenus en attente et ajoute à la blocklist.

DELETE


                                                https://manuscry.com/api/contacts/{leadId}/block

Paramètres

Nom	Type	Requis	Description
leadId	string	Oui	ID hashé du contact

Exemple de requête

curl -X DELETE "https://manuscry.com/api/contacts/{leadId}/block" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/contacts/{leadId}/block', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/contacts/{leadId}/block');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Lead blocked successfully.",
    "data": {
        "lead_id": "aBc123Xy",
        "blocked_email": "contact@example.com",
        "duplicates_blocked": 2,
        "emails_cancelled": 0,
        "letters_cancelled": 1
    }
}

Actions automatiques :

Le contact et tous ses doublons (même email) sont bloqués

L'email est ajouté à votre blocklist

L'adresse postale est ajoutée à la blocklist si disponible

Toutes les lettres en attente (avant génération) sont annulées

Retour :

duplicates_blocked : Nombre de doublons bloqués en plus du contact principal

emails_cancelled : Toujours 0 pour Manuscry

letters_cancelled : Nombre de lettres annulées

Liste de blocage

Récupère la liste de blocage.

GET


                                                https://manuscry.com/api/blocklist

Paramètres

Nom	Type	Requis	Description
type	string	Non	Type de blocage (email, domain, company, siren, address, all)
page	integer	Non	Numéro de page
per_page	integer	Non	Éléments par page

Exemple de requête

curl -X GET "https://manuscry.com/api/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/blocklist', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/blocklist');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "type": "email",
            "value": "spam@example.com",
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        },
        {
            "id": "dEf456Zw",
            "type": "company",
            "value": "concurrent sarl",
            "created_at": "2024-01-14T15:20:00.000000Z",
            "updated_at": "2024-01-14T15:20:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "per_page": 25,
        "to": 2,
        "total": 2
    }
}

Types disponibles :

email : Adresse email exacte

domain : Nom de domaine

company : Nom d'entreprise (recherche approximative)

siren : Numéro SIREN (9 chiffres)

address : Identité complète (format: firstname_slug|lastname_slug|zip)

Ajouter à la blocklist

Ajoute un élément à bloquer.

POST


                                                https://manuscry.com/api/blocklist

Paramètres

Nom	Type	Requis	Description
type	string	Oui	Type (email, domain, company, siren, address)
value	string	Oui	Valeur à bloquer

Exemple de requête

curl -X POST "https://manuscry.com/api/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "value": "unwanted@spam.com"
}'

const response = await fetch('https://manuscry.com/api/blocklist', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "type": "email",
      "value": "unwanted@spam.com"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/blocklist');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "type": "email",
    "value": "unwanted@spam.com"
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Item added to blocklist successfully",
    "data": {
        "id": "aBc123Xy",
        "type": "email",
        "value": "unwanted@spam.com",
        "created_at": "2024-01-22T10:30:00.000000Z"
    }
}

Supprimer de la blocklist

Supprime un élément de la blocklist par ID ou par valeur.

DELETE


                                                https://manuscry.com/api/blocklist

Paramètres

Nom	Type	Requis	Description
id	string	Non	ID hashé de l'élément à supprimer
value	string	Non	Valeur à débloquer (alternative à id)

Exemple de requête

curl -X DELETE "https://manuscry.com/api/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Par ID": {
        "id": "aBc123Xy"
    },
    "Par valeur": {
        "value": "unwanted@spam.com"
    }
}'

const response = await fetch('https://manuscry.com/api/blocklist', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "Par ID": {
          "id": "aBc123Xy"
      },
      "Par valeur": {
          "value": "unwanted@spam.com"
      }
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/blocklist');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "Par ID": {
        "id": "aBc123Xy"
    },
    "Par valeur": {
        "value": "unwanted@spam.com"
    }
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Item removed from blocklist successfully"
}

Méthodes de suppression :

Par ID : Utilisez le paramètre id avec l'ID hashé récupéré depuis GET /api/blocklist

Par valeur : Utilisez le paramètre value avec la valeur exacte

Note : Au moins un des deux paramètres (id ou value) doit être fourni. Si les deux sont fournis, id est prioritaire.

Liste des courriers

Récupère les courriers de toutes vos campagnes.

GET


                                                https://manuscry.com/api/letters

Paramètres

Nom	Type	Requis	Description
category	string	Non	Catégorie de courriers
page	integer	Non	Numéro de page
per_page	integer	Non	Éléments par page (1-100)
search	string	Non	Recherche textuelle
campaign_filter	string	Non	ID hashé de la campagne (recommandé - alias agent_filter accepté)
lead_identifier	string	Non	Identifiant unique du contact (celui fourni lors de l'ajout via API ou l'interface)
self_print_only	boolean	Non	Ne retourner que les courriers des campagnes en impression autonome (self-print)

Exemple de requête

curl -X GET "https://manuscry.com/api/letters" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/letters', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/letters');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "lead_id": "dEf456Zw",
            "lead_identifier": "contact_unique_001",
            "lead_name": "Jean Dupont",
            "company_name": "TechCorp SAS",
            "format": "a6",
            "status": "delivered",
            "status_label": "Livré",
            "tracking_code": "BATCH-20240115-abc123",
            "content_preview": "Bonjour Jean, je vous contacte...",
            "has_qr_code": true,
            "qr_code_scanned": true,
            "qr_code_scanned_at": "2024-01-20T14:30:00.000000Z",
            "qr_code_scan_count": 3,
            "is_returned": false,
            "is_printed": false,
            "printed_at": null,
            "sent_at": "2024-01-16T09:00:00.000000Z",
            "delivered_at": "2024-01-18T14:30:00.000000Z",
            "scheduled_at": null,
            "address": {
                "line1": "TechCorp SAS",
                "line2": "Jean Dupont",
                "line3": "123 rue de Rivoli",
                "zip": "75001",
                "city": "Paris",
                "country": "FRANCE"
            },
            "campaign": {
                "id": "gHi789Uv",
                "name": "Campagne Printemps 2024"
            },
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-20T14:45:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "per_page": 25,
        "to": 25,
        "total": 72
    }
}

Catégories disponibles :

to_validate : Courriers en attente de validation

validated : Courriers validés en attente d'envoi

rejected : Courriers refusés en attente de suppression

error : Courriers en erreur

insufficient_funds : Courriers en attente de crédits

in_preparation : Courriers en génération, impression ou attente d'envoi

transiting : Courriers en transit postal

delivered : Courriers délivrés

returned : Courriers retournés (NPAI/PND)

scanned : Courriers avec QR code flashé

not_scanned : Courriers avec QR code non flashé

Filtrage par identifiant :

Le paramètre lead_identifier permet de retrouver les courriers d'un contact spécifique en utilisant l'identifiant unique fourni lors de l'ajout (via API ou interface). Combiné avec campaign_filter, il permet de retrouver précisément un courrier.

Statuts disponibles :

validating : En attente de validation utilisateur

generating : En cours de génération des visuels

printing : En attente d'impression

sending : En attente d'envoi

transiting : En transit

delivered : Livré

returned : Retourné (NPAI/PND)

cancelled : Annulé

error : Erreur technique

Courriers en attente de validation

Récupère la liste des courriers en attente de validation.

GET


                                                https://manuscry.com/api/letters/to-validate

Paramètres

Nom	Type	Requis	Description
page	integer	Non	Numéro de page
per_page	integer	Non	Éléments par page (1-100)
campaign_filter	string	Non	ID hashé de la campagne (recommandé - alias agent_filter accepté)

Exemple de requête

curl -X GET "https://manuscry.com/api/letters/to-validate" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/letters/to-validate', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/letters/to-validate');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "lead_id": "dEf456Zw",
            "lead_name": "Jean Dupont",
            "company_name": "TechCorp SAS",
            "format": "a6",
            "status": "validating",
            "tracking_code": "BATCH-20240115-abc123",
            "content_preview": "Bonjour Jean, je vous contacte...",
            "has_qr_code": true,
            "campaign": {
                "id": "gHi789Uv",
                "name": "Campagne Printemps 2024"
            },
            "address": {
                "line1": "TechCorp SAS",
                "line2": "Jean Dupont",
                "line3": "123 rue de Rivoli",
                "zip": "75001",
                "city": "Paris",
                "country": "FRANCE"
            },
            "created_at": "2024-01-15T10:30:00.000000Z",
            "autovalidated_at": null,
            "actions": {
                "validate": "https://manuscry.com/api/letters/validate/aBc123Xy",
                "reject": "https://manuscry.com/api/letters/reject/aBc123Xy"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "per_page": 12,
        "to": 12,
        "total": 23
    }
}

Valider un courrier

Valide un courrier pour envoi automatique.

POST


                                                https://manuscry.com/api/letters/validate/{letterId}

Paramètres

Nom	Type	Requis	Description
letterId	string	Oui	ID hashé du courrier
blocks	array	Non	Blocs de contenu personnalisés

Exemple de requête

curl -X POST "https://manuscry.com/api/letters/validate/{letterId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [
        {
            "id": "block_123",
            "content": "Contenu personnalisé"
        }
    ]
}'

const response = await fetch('https://manuscry.com/api/letters/validate/{letterId}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "blocks": [
          {
              "id": "block_123",
              "content": "Contenu personnalisé"
          }
      ]
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/letters/validate/{letterId}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "blocks": [
        {
            "id": "block_123",
            "content": "Contenu personnalisé"
        }
    ]
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Letter validated successfully - will be sent automatically in 60min",
    "data": {
        "letter_id": "aBc123Xy",
        "scheduled_validate_at": "2024-01-22T11:30:00.000000Z",
        "validation_delay_minutes": 60
    }
}

Délai de carence :

Le courrier sera validé définitivement après 60 minutes.

Pendant ce délai, vous pouvez encore le refuser.

Refuser un courrier

Refuse un courrier.

POST


                                                https://manuscry.com/api/letters/reject/{letterId}

Paramètres

Nom	Type	Requis	Description
letterId	string	Oui	ID hashé du courrier

Exemple de requête

curl -X POST "https://manuscry.com/api/letters/reject/{letterId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/letters/reject/{letterId}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/letters/reject/{letterId}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Letter rejected successfully - will be deleted automatically in 60min",
    "data": {
        "letter_id": "aBc123Xy",
        "scheduled_delete_at": "2024-01-22T11:30:00.000000Z",
        "validation_delay_minutes": 60
    }
}

Délai de carence :

Le courrier sera supprimé définitivement après 60 minutes.

Pendant ce délai, vous pouvez encore le valider.

Liste des courriers impression autonome

Récupère les courriers d'une campagne en impression autonome avec les URLs des fichiers haute définition à imprimer.

GET


                                                https://manuscry.com/api/letters

Paramètres

Nom	Type	Requis	Description
campaign_filter	string	Oui	ID hashé de la campagne self-print (recommandé - alias agent_filter accepté)
category	string	Non	Catégorie (delivered recommandé pour récupérer les courriers prêts)
page	integer	Non	Numéro de page
per_page	integer	Non	Éléments par page (1-100)

Exemple de requête

curl -X GET "https://manuscry.com/api/letters" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/letters', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/letters');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "data": [
        {
            "id": "aBc123Xy",
            "lead_id": "dEf456Zw",
            "lead_name": "Jean Dupont",
            "company_name": "TechCorp SAS",
            "format": "a6",
            "status": "delivered",
            "tracking_code": "BATCH-20250115-abc123",
            "is_printed": false,
            "printed_at": null,
            "campaign": {
                "id": "gHi789Uv",
                "name": "Campagne E-commerce",
                "is_self_print": true,
                "print_files": {
                    "front_url": "https://cdn.manuscry.com/letters/front_abc123.png",
                    "back_url": "https://cdn.manuscry.com/letters/back_abc123.png"
                }
            },
            "created_at": "2025-01-15T10:30:00.000000Z",
            "updated_at": "2025-01-15T10:30:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "per_page": 25,
        "to": 25,
        "total": 15
    }
}

Spécificités impression autonome :

Pour les campagnes en mode impression autonome (is_self_print: true), l'objet campaign contient des champs additionnels :

is_self_print : Indique qu'il s'agit d'une campagne impression autonome

print_files : URLs des fichiers haute définition à télécharger et imprimer

front_url : Image du recto à imprimer

back_url : Image du verso (null pour les formats recto seul, ex. A4)

Workflow d'impression :

Utilisez category=delivered pour récupérer uniquement les courriers générés et prêts à imprimer

Téléchargez les fichiers depuis les URLs fournies dans print_files

Imprimez les fichiers en haute qualité (300 DPI recommandé)

Une fois imprimé, marquez le courrier comme tel via /api/letters/mark-printed/{letterId}

Dimensions des fichiers :

Formats supportés : a6, a6-vertical, a5, a5-vertical, a4, dl, dl-vertical (les formats publics sont a6, dl, a5 et a4 ; les variantes verticales restent réservées à l'admin)

Exemple - Format A6 : 2400px x 1702px (148mm x 105mm en mode paysage)

Exemple - Format A4 : 2400px x 3394px (210mm x 297mm en mode portrait)

Images PNG haute résolution, prêtes pour impression directe

Pas d'enveloppe fournie (impression client uniquement)

Marquer un courrier comme imprimé

Marque un courrier comme imprimé dans votre système. Permet de suivre les courriers que vous avez déjà imprimés.

POST


                                                https://manuscry.com/api/letters/mark-printed/{letterId}

Paramètres

Nom	Type	Requis	Description
letterId	string	Oui	ID hashé du courrier à marquer comme imprimé

Exemple de requête

curl -X POST "https://manuscry.com/api/letters/mark-printed/{letterId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/letters/mark-printed/{letterId}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/letters/mark-printed/{letterId}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Letter marked as printed successfully",
    "data": {
        "letter_id": "aBc123Xy",
        "is_printed": true,
        "printed_at": "2025-01-22T14:30:00.000000Z"
    }
}

Fonctionnement :

Cet endpoint est réservé exclusivement aux campagnes en impression autonome

Permet de tracker les courriers que vous avez déjà imprimés dans votre système

Le champ is_printed passe à true et printed_at est automatiquement enregistré avec l'horodatage

Cette action est irréversible mais n'affecte pas le statut du courrier (reste delivered)

Restrictions :

Disponible uniquement pour les campagnes avec is_self_print: true

Impossible de modifier les courriers de campagnes annulées (status: cancelled)

Retourne une erreur 403 si utilisé sur une campagne non self-print

Utilisation recommandée :

Appelez cet endpoint après avoir téléchargé et imprimé physiquement le courrier pour maintenir un suivi précis de vos impressions.

Webhook courrier impression autonome prêt

Webhook déclenché automatiquement quand un courrier en impression autonome est généré et prêt au téléchargement.

Événement : self_print_letter_ready

Déclenchement : Ce webhook est envoyé automatiquement quand un courrier d'une campagne self-print est généré avec succès. Les URLs des images haute définition sont incluses dans le payload pour téléchargement immédiat.

Configuration : Configurez ce webhook dans Manuscry > Paramètres > Webhooks

Payload envoyé

{
    "event": "self_print_letter_ready",
    "timestamp": "2025-01-15T10:30:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Self-Print",
    "data": {
        "letter": {
            "id": "gHi789Uv",
            "lead_id": "dEf456Zw",
            "lead_identifier": "contact_unique_001",
            "lead_name": "Jean Dupont",
            "company_name": "TechCorp SAS",
            "format": "a6",
            "front_url": "https://cdn.manuscry.com/letters/front_abc123.png",
            "back_url": "https://cdn.manuscry.com/letters/back_abc123.png",
            "ready_at": "2025-01-15T10:30:00.000000Z"
        }
    }
}

Utilisation recommandée :

Téléchargez automatiquement les fichiers depuis les URLs fournies
Déclenchez votre flux d'impression automatique
Notifiez vos équipes logistiques qu'un nouveau courrier est prêt

Preview d'un courrier

Génère une image de preview d'un courrier avec des valeurs personnalisées. Cette route est réservée aux partenaires intégrant un éditeur de courriers dans leur propre application. L'accès est soumis à activation manuelle par l'équipe Manuscry.

POST


                                                https://manuscry.com/api/partners/campaigns/{campaign_id}/preview

Paramètres

Nom	Type	Requis	Description
campaign_id	string	Oui	ID hashé de la campagne (visible dans l'URL de votre campagne)
fields	object	Oui	Objet contenant les valeurs des champs personnalisés à injecter dans le template du courrier. Les clés correspondent aux variables {variable} configurées dans l'éditeur de la campagne.
surface	string	Non	Surface à rendre : "front" (recto, par défaut) ou "back" (verso - formats carte a6, dl, a5)
width	integer	Non	Largeur de l'image de sortie en pixels (200-1500, défaut: 450). Le rendu est effectué en haute définition puis redimensionné à la largeur demandée.

Exemple de requête

curl -X POST "https://manuscry.com/api/partners/campaigns/{campaign_id}/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
        "firstname": "Jean",
        "lastname": "Dupont",
        "company": "TechCorp SAS",
        "city": "Paris"
    },
    "surface": "front",
    "width": 450
}'

const response = await fetch('https://manuscry.com/api/partners/campaigns/{campaign_id}/preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "fields": {
          "firstname": "Jean",
          "lastname": "Dupont",
          "company": "TechCorp SAS",
          "city": "Paris"
      },
      "surface": "front",
      "width": 450
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/partners/campaigns/{campaign_id}/preview');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "fields": {
        "firstname": "Jean",
        "lastname": "Dupont",
        "company": "TechCorp SAS",
        "city": "Paris"
    },
    "surface": "front",
    "width": 450
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Accès restreint - Activation manuelle requise

Cette route est réservée aux partenaires qui intègrent un éditeur de courriers Manuscry dans leur propre application (SaaS, CRM, ERP, etc.). Pour activer l'accès API Partenaire sur votre campagne, contactez-nous directement.

Fonctionnement

La preview retourne une image PNG du courrier avec un watermark semi-transparent superposé. Le rendu est effectué en haute définition (taille production) puis redimensionné à la largeur demandée. Aucun crédit n'est consommé en mode preview, aucun enregistrement n'est créé dans votre boîte postale. Cette route est limitée à 10 requêtes par minute, la mise en place d'un throttle du côté de votre application est nécessaire.

Rendu définitif

Pour envoyer un courrier réel, utilisez le workflow classique de commande asynchrone via POST /api/campaigns/{campaign_id}/contacts. Sur les campagnes en impression autonome (self-print), les images haute définition sont disponibles via le webhook self_print_letter_ready ou l'endpoint GET /api/letters.

Variables disponibles

Les variables dépendent de la configuration de votre campagne dans l'éditeur. Utilisez GET /api/campaigns/{campaign_id}/settings pour récupérer la liste des champs configurés.

Historique des rendez-vous calendrier

Récupère l'historique des rendez-vous pris via la page de booking calendrier d'une campagne.

GET


                                                https://manuscry.com/api/campaigns/{campaignId}/calendar-events

Paramètres

Nom	Type	Requis	Description
campaignId	string	Oui	ID hashé de la campagne
page	integer	Non	Numéro de page
per_page	integer	Non	Éléments par page (1-50)

Exemple de requête

curl -X GET "https://manuscry.com/api/campaigns/{campaignId}/calendar-events" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/campaigns/{campaignId}/calendar-events', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/campaigns/{campaignId}/calendar-events');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "campaign": {
        "id": "aBc123Xy",
        "name": "Campagne Printemps 2024"
    },
    "data": [
        {
            "id": "xYz789Qw",
            "contact_name": "Marie Durand",
            "contact_email": "marie.durand@example.com",
            "contact_firstname": "Marie",
            "contact_lastname": "Durand",
            "contact_phone": "+33612345678",
            "meeting_mode": "visio",
            "scheduled_at": "2024-01-25T10:00:00.000000Z",
            "timezone": "Europe/Paris",
            "google_event_id": "abc123xyz",
            "google_event_link": "https://calendar.google.com/event?eid=abc123xyz",
            "status": "success",
            "created_at": "2024-01-22T14:30:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "per_page": 10,
        "to": 10,
        "total": 15
    }
}

Endpoints disponibles :

/api/campaigns/{campaignId}/calendar-events (recommandé pour Manuscry)

/api/agents/{agentId}/calendar-events (alias fonctionnel pour compatibilité)

Modes de rendez-vous (meeting_mode) :

visio : Rendez-vous en visioconférence (mode par défaut)

phone : Le prospect demande à être appelé au numéro fourni

Les rendez-vous antérieurs à l'introduction du champ remontent visio.

Statuts possibles :

success : Événement créé avec succès dans Google Calendar

failed : Échec de création dans Google Calendar (événement sauvegardé localement)

calendar_disconnected : Calendrier Google non connecté (événement sauvegardé localement)

Important :

Cet historique est un log local des réservations effectuées via la page de booking.

Il n'est pas synchronisé avec Google Calendar et sert uniquement de journal d'audit.

Webhooks

Les webhooks permettent de recevoir des notifications en temps réel des événements de vos campagnes Manuscry.

Configuration : Interface Manuscry > Paramètres > Webhooks

Webhooks disponibles :

Filtrage par campagne configurable
Stockés dans votre compte utilisateur
Configuration d'URL par type d'événement

Format général des webhooks : Chaque webhook est envoyé en POST avec le format JSON suivant :

Format général

{
    "event": "event_type",
    "timestamp": "2024-01-20T14:30:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "dEf456Zw",
    "campaign_name": "Ma campagne",
    "data": []
}

Événements courriers disponibles :

1. letter_ready_for_validation - Courrier prêt à être validé

Déclenché lorsqu'un courrier a été généré et attend validation.

Payload letter_ready_for_validation

{
    "event": "letter_ready_for_validation",
    "timestamp": "2024-01-20T14:30:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Printemps 2024",
    "data": {
        "lead": {
            "id": "dEf456Zw",
            "lead_identifier": "CONTACT-001",
            "firstname": "Jean",
            "lastname": "Dupont",
            "email": "jean.dupont@entreprise.com",
            "company": "TechCorp SAS"
        }
    }
}

2. letter_sent - Courrier envoyé au service postal

Déclenché lorsqu'un courrier validé est envoyé à l'impression et à la poste.

Payload letter_sent

{
    "event": "letter_sent",
    "timestamp": "2024-01-20T14:30:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Printemps 2024",
    "data": {
        "letter": {
            "id": "gHi789Uv",
            "lead_id": "dEf456Zw",
            "lead_identifier": "CONTACT-002",
            "recipient_name": "Jean Dupont",
            "recipient_company": "TechCorp SAS",
            "recipient_address": "123 rue de Rivoli, 75001 Paris",
            "tracking_number": "BATCH-20240120-abc123",
            "sent_at": "2024-01-20T14:30:00.000000Z"
        }
    }
}

3. letter_delivered - Courrier livré au destinataire

Déclenché lorsque le courrier est confirmé livré par La Poste.

Payload letter_delivered

{
    "event": "letter_delivered",
    "timestamp": "2024-01-22T10:15:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Printemps 2024",
    "data": {
        "letter": {
            "id": "gHi789Uv",
            "lead_id": "dEf456Zw",
            "lead_identifier": "CONTACT-002",
            "recipient_name": "Jean Dupont",
            "recipient_company": "TechCorp SAS",
            "tracking_number": "BATCH-20240120-abc123",
            "delivered_at": "2024-01-22T10:15:00.000000Z"
        }
    }
}

4. letter_returned - Courrier retourné (NPAI/PND)

Déclenché lorsqu'un courrier est retourné par La Poste (adresse incorrecte).

Payload letter_returned

{
    "event": "letter_returned",
    "timestamp": "2024-01-25T09:30:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Printemps 2024",
    "data": {
        "letter": {
            "id": "gHi789Uv",
            "lead_id": "dEf456Zw",
            "lead_identifier": "CONTACT-003",
            "recipient_name": "Jean Dupont",
            "recipient_company": "TechCorp SAS",
            "tracking_number": "BATCH-20240120-abc123",
            "return_reason": "Adresse incorrecte",
            "returned_at": "2024-01-25T09:30:00.000000Z"
        }
    }
}

5. qr_code_scanned - QR code flashé sur un courrier

Déclenché lorsqu'un destinataire scanne le QR code sur un courrier.

Payload qr_code_scanned

{
    "event": "qr_code_scanned",
    "timestamp": "2024-01-21T16:45:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Printemps 2024",
    "data": {
        "scan": {
            "letter_id": "gHi789Uv",
            "lead_id": "dEf456Zw",
            "lead_identifier": "CONTACT-004",
            "recipient_name": "Jean Dupont",
            "recipient_company": "TechCorp SAS",
            "scan_location": {
                "country": "France",
                "city": "Paris",
                "latitude": 48.8566,
                "longitude": 2.3522
            },
            "scan_device": {
                "platform": "iOS",
                "browser": "Safari"
            },
            "scanned_at": "2024-01-21T16:45:00.000000Z"
        }
    }
}

6. new_calendar_event - Nouveau rendez-vous calendrier

Déclenché lorsqu'un rendez-vous est pris via la page de réservation calendrier.

Payload new_calendar_event

{
    "event": "new_calendar_event",
    "timestamp": "2024-01-22T14:30:00.000000Z",
    "user_id": "aBc123Xy",
    "campaign_id": "xYz789Ab",
    "campaign_name": "Campagne Printemps 2024",
    "data": {
        "appointment": {
            "id": "xYz456Qw",
            "contact_firstname": "Marie",
            "contact_lastname": "Durand",
            "contact_email": "marie.durand@example.com",
            "contact_phone": "+33612345678",
            "meeting_mode": "visio",
            "scheduled_at": "2024-01-25T10:00:00.000000Z",
            "timezone": "Europe/Paris",
            "google_event_id": "abc123xyz",
            "google_event_link": "https://calendar.google.com/event?eid=abc123xyz",
            "status": "success"
        }
    }
}

Statuts possibles :

success : Événement créé avec succès dans Google Calendar
failed : Échec de création dans Google Calendar (événement sauvegardé localement)
calendar_disconnected : Calendrier Google non connecté (événement sauvegardé localement)

Modes de rendez-vous (meeting_mode) :

visio : Rendez-vous en visioconférence (mode par défaut)
phone : Le prospect demande à être appelé au numéro fourni

Identité du contact : le formulaire de réservation ne collecte plus de nom - contact_firstname et contact_lastname proviennent du lead correspondant quand il est identifié, null sinon.

Rechercher une adresse postale

Lance une recherche d'adresse postale à partir d'une URL LinkedIn ou d'informations de contact.

POST


                                                https://manuscry.com/api/find-postal-address

Paramètres

Nom	Type	Requis	Description
linkedin_url	string	Non	URL complète du profil LinkedIn (requis si contact_info absent)
contact_info	object	Non	Informations de contact (requis si linkedin_url absent)
contact_info.first_name	string	Oui	Prénom de la personne
contact_info.last_name	string	Oui	Nom de la personne
contact_info.company_name	string	Oui	Nom de l'entreprise
contact_info.additional_info	string	Non	Informations complémentaires (poste, secteur, localisation)

Exemple de requête

curl -X POST "https://manuscry.com/api/find-postal-address" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/johndoe/"
}'

const response = await fetch('https://manuscry.com/api/find-postal-address', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "linkedin_url": "https://www.linkedin.com/in/johndoe/"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/find-postal-address');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$data = '{
    "linkedin_url": "https://www.linkedin.com/in/johndoe/"
}';
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "message": "Address search initiated successfully",
    "data": {
        "search_id": "abc123def456",
        "status": "processing",
        "estimated_completion": "Within 5-10 minutes",
        "lead_data": {
            "first_name": "John",
            "last_name": "Doe",
            "company_name": "Acme Corp",
            "linkedin_url": "https://www.linkedin.com/in/johndoe/",
            "created_at": "2025-09-25T10:30:00Z"
        },
        "credits_remaining": 45
    }
}

Coût : 25 crédits par recherche (0.25€ HT). Le débit a lieu à l'initiation, que la recherche aboutisse ou non.

Idempotence : un POST identique (même linkedin_url ou même contact_info) par le même utilisateur sous 24h renvoie la recherche déjà créée (already_exists: true, même search_id) sans nouveau débit. Sûr pour les retries (Zapier/Make, timeouts réseau).

Facturation sans résultat : si aucune adresse n'est trouvée, le crédit reste consommé (on facture la recherche, pas le résultat). Un remboursement automatique n'a lieu qu'en cas d'erreur technique interne après le débit.

Traitement asynchrone :

Les recherches sont traitées de manière asynchrone (cycle de traitement toutes les ~15 minutes).

Utilisez l'endpoint de récupération des résultats pour obtenir les adresses trouvées.

Types de recherche :

Par URL LinkedIn : Envoyez uniquement le paramètre linkedin_url

Par informations de contact : Envoyez l'objet contact_info avec first_name, last_name, company_name et optionnellement additional_info

Workflows utilisés :

Le système utilise plusieurs sources pour maximiser les chances de trouver des adresses :

Analyse LinkedIn (profil et entreprise)

Recherche intelligente sur le web avec IA

Crawling de sites web d'entreprise

Déduplication et scoring automatique

Réponses d'erreur :

402 : Crédits insuffisants (besoin d'au moins 25 crédits)

422 : Validation échouée (paramètres manquants ou invalides)

500 : Erreur interne (le crédit est automatiquement remboursé)

Récupérer les résultats d'une recherche

Récupère les résultats d'une recherche d'adresse en utilisant l'ID retourné lors de la création.

GET


                                                https://manuscry.com/api/find-postal-address/{search_id}

Paramètres

Nom	Type	Requis	Description
search_id	string	Oui	ID de la recherche retourné lors de la création

Exemple de requête

curl -X GET "https://manuscry.com/api/find-postal-address/{search_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://manuscry.com/api/find-postal-address/{search_id}', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://manuscry.com/api/find-postal-address/{search_id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Exemple de réponse

{
    "success": true,
    "data": {
        "search_id": "abc123def456",
        "status": "completed",
        "search_data": {
            "first_name": "John",
            "last_name": "Doe",
            "company_name": "Acme Corporation",
            "linkedin_url": "https://www.linkedin.com/in/johndoe/",
            "created_at": "2025-09-25T10:30:00Z",
            "processed_at": "2025-09-25T10:35:00Z"
        },
        "results": {
            "success": true,
            "total_addresses_found": 2,
            "search_summary": "2 adresses uniques trouvées via LinkedIn API et crawling web",
            "addresses": [
                {
                    "confidence_score": 9,
                    "sources_summary": "LinkedIn API officielle",
                    "source_count": 1,
                    "address": {
                        "address_line1": "Acme Corporation",
                        "address_line2": "John Doe",
                        "address_line3": "12 rue de la Paix",
                        "address_zip": "75001",
                        "address_city": "Paris",
                        "address_country": "France",
                        "address_full": "Acme Corporation, John Doe, 12 rue de la Paix, 75001 Paris, France"
                    }
                },
                {
                    "confidence_score": 7,
                    "sources_summary": "Crawling site web entreprise",
                    "source_count": 1,
                    "address": {
                        "address_line1": "Acme Corp - Siège Social",
                        "address_line2": "John Doe",
                        "address_line3": "456 Avenue des Champs-Élysées",
                        "address_zip": "75008",
                        "address_city": "Paris",
                        "address_country": "France",
                        "address_full": "Acme Corp - Siège Social, John Doe, 456 Avenue des Champs-Élysées, 75008 Paris, France"
                    }
                }
            ]
        }
    }
}

Statuts de recherche :

processing : La recherche est en cours. Le champ processed_at est null. Attendez 5-10 minutes avant de rappeler l'API.

completed : La recherche est terminée avec succès. Le champ results contient les adresses trouvées.

failed : La recherche a échoué. Le champ error_details contient plus d'informations.

Scores de confiance :

Chaque adresse trouvée est accompagnée d'un score de confiance sur 10 :

9-10 : Très haute confiance (source officielle comme LinkedIn API)

7-8 : Haute confiance (sites web officiels, sources multiples)

5-6 : Confiance moyenne (sources secondaires fiables)

3-4 : Faible confiance (sources non vérifiées)

Polling recommandé :

Implémentez un polling avec un intervalle de 20 secondes pour vérifier régulièrement le statut des recherches en cours.

Réponse en cours de traitement :

Si la recherche est toujours en cours (status: processing), le champ processed_at sera null et results ne sera pas présent.

Réponses d'erreur :

400 : search_id invalide

403 : Accès refusé (la recherche appartient à un autre utilisateur)

404 : Recherche introuvable

500 : Erreur interne

Webinar découverte

Documentation API Manuscry - v1.0

Introduction

Authentification

Serveur MCP (Model Context Protocol)

Récupérer la configuration d'une campagne

Paramètres

Exemple de requête

Exemple de réponse

Statistiques d'une campagne

Paramètres

Exemple de requête

Exemple de réponse

Envoyer un courrier (ajout manuel)

Paramètres

Exemple de requête

Exemple de réponse

Programmer une carte d'anniversaire

Paramètres

Exemple de requête

Exemple de réponse

Envoyer un courrier à partir d'un profil LinkedIn

Paramètres

Exemple de requête

Exemple de réponse

Générer un courrier en impression autonome

Paramètres

Exemple de requête

Exemple de réponse

Informations utilisateur

Exemple de requête

Exemple de réponse

Liste des contacts

Paramètres

Exemple de requête

Exemple de réponse

Bloquer un contact

Paramètres

Exemple de requête

Exemple de réponse

Liste de blocage

Paramètres

Exemple de requête

Exemple de réponse

Ajouter à la blocklist

Paramètres

Exemple de requête

Exemple de réponse

Supprimer de la blocklist

Paramètres

Exemple de requête

Exemple de réponse

Liste des courriers

Paramètres

Exemple de requête

Exemple de réponse

Courriers en attente de validation

Paramètres

Exemple de requête

Exemple de réponse

Valider un courrier

Paramètres

Exemple de requête

Exemple de réponse

Refuser un courrier

Paramètres

Exemple de requête

Exemple de réponse

Liste des courriers impression autonome

Paramètres

Exemple de requête

Exemple de réponse

Marquer un courrier comme imprimé

Paramètres

Exemple de requête

Exemple de réponse

Webhook courrier impression autonome prêt

Payload envoyé

Preview d'un courrier

Paramètres