Email API documentation

Comment fonctionne request_id

1. Vérifiez le nombre de lignes avec action=preview. Aucun request_id n’est nécessaire et aucune ligne n’est supprimée.
2. Générez un request_id unique pour une nouvelle suppression, par exemple un UUID. Conservez-le avant d’envoyer action=delete.
3. Pour reprendre après une erreur, un délai dépassé ou une réponse HTTP 202, réutilisez la même clé API, le même endpoint d’historique, le même request_id et la même valeur include_linked. Ne générez jamais automatiquement un nouvel identifiant après une erreur.
4. Lorsque completed=true, l’opération est terminée. Réutiliser son identifiant renvoie le même résultat sans supprimer les nouvelles lignes arrivées entre-temps. Utilisez un nouvel identifiant uniquement pour démarrer volontairement un nouveau nettoyage.

request_id identifie votre opération de suppression, et non un SMS individuel. Format autorisé : 16-128 lettres, chiffres, tirets ou soulignements ASCII. Un UUID généré avec crypto.randomUUID() est approprié.

La suppression s’effectue par lots. Une réponse HTTP 202 avec continue_required=true demande de répéter action=delete après 3 secondes. Aucun cron ne prend le relais. action=status consulte uniquement l’avancement, même si la réponse HTTP vaut 200.

Exemples de suppression et de consultation de l’avancement

Remplacez le request_id d’exemple par votre propre identifiant unique avant de commencer. Les requêtes delete ci-dessous modifient réellement l’historique du compte : ce ne sont pas des aperçus.

curl -X POST "https://api.smsmobileapi.com/delete-history-email/" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  -d "action=delete" -d "include_linked=0" \
  -d "request_id=6d54ac58-41f1-4fbc-9a39-6e6c86089451"

curl -X POST "https://api.smsmobileapi.com/delete-history-email/" \
  -H "Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN" \
  -d "action=delete" -d "include_linked=0" \
  -d "request_id=6d54ac58-41f1-4fbc-9a39-6e6c86089451"

curl -G "https://api.smsmobileapi.com/delete-history-email/" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  -d "action=status" \
  -d "request_id=6d54ac58-41f1-4fbc-9a39-6e6c86089451"

GET accepte aussi action=preview ou action=delete. POST est recommandé : les paramètres d’URL peuvent apparaître dans l’historique du navigateur et les journaux serveur. N’insérez jamais une URL de suppression dans un lien public, une image ou un mécanisme de préchargement.

Pour POST, envoyez tous les paramètres du corps du formulaire ou d'un objet JSON, jamais dans la chaîne de requête. Les paramètres inconnus sont rejetés; les filtres mobiles ou la date ne sont pas pris en charge.

Authentification des endpoints d’historique

Utiliser apikey ou un jeton d'accès Authorization: Bearer émis par SMSMobileAPI OAuth2. N'envoyez pas de jeton de rafraîchissement ou de clé API sous forme de jeton Bearer. Les jetons périmés sont refusés.

Lorsque des scopes sont définis, history:read autorise preview et status ; history:delete autorise aussi la suppression. Les restrictions du jeton et du client OAuth s’appliquent toutes les deux. Les anciens jetons sans scope conservent leur accès existant au compte.

OAuth2 sélectionne la clé API primaire unique. Si plusieurs clés primaires existent, fournir également apikey pour sélectionner une appartenant au compte. Les clés secondaires n'accordent jamais l'accès à l'historique de la clé primaire.

Lire la réponse avant de continuer

count_delete est le nombre cumulatif retiré par cette opération. selected_at_start est la sélection initiale; protected_at_start compte les enregistrements exclus. Utilisez preview.linked_or_processing pour compter les enregistrements liés même lorsque include_linked=1.

{
    "result": {
        "error": 0,
        "history": "email",
        "action": "delete",
        "request_id": "6d54ac58-41f1-4fbc-9a39-6e6c86089451",
        "status": "processing",
        "completed": false,
        "count_delete": 100,
        "total_before": 250,
        "selected_at_start": 200,
        "protected_at_start": 50,
        "include_linked": 0,
        "continue_required": true,
        "message": "Repeat GET or POST with the same request_id and include_linked to continue. Status requests do not run deletion."
    }
}

• 200 avec completed=true : terminé. Une réponse HTTP 200 à preview ou status ne suffit pas, à elle seule, à confirmer la fin de la suppression.
• 400 INVALID_REQUEST_ID : vérifiez le format de l’identifiant. 404 REQUEST_NOT_FOUND : aucune opération ne correspond à cet identifiant, cette clé API et cet historique.
• 401 : identifiants invalides ou expirés. 403 : autorisations OAuth insuffisantes ou compte non autorisé.
• 409 HISTORY_BUSY : un autre nettoyage est en cours ; continuez-le depuis le client original. 409 INCLUDE_LINKED_CONFLICT : restaurer la valeur originale de include_linked.
• 409 OAUTH_ACCOUNT_AMBIGUOUS: fournir une clé API appartenant à ce compte.
• 503 ou interruption du réseau : certains lots peuvent déjà être complétés. Vérifiez la configuration, puis reessayez avec le request_id original. Ne créez pas automatiquement une opération de remplacement.