Obtenir un sujet

GET /api/v1/topics/{topicId} Un sujet, plus ce qu'il coûte : le nombre de refus enregistrés sur lui, et les campagnes et séquences qui le portent. C'est ce qui vous dit à l'avance pourquoi une suppression sera refusée.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Refusé — `403`

Celui-ci est plus strict que la liste : savoir ce que contient un sujet relève du même droit que le supprimer. Un member peut toujours lire les noms et les identifiants avec Lister les sujets. Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Paramètres de chemin

Paramètre	Type	Description
`topicId`	string	Obligatoire. Le sujet à lire

Exemple

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/topics/$TOPIC_ID"

Réponse

200 OK — le sujet et son usage.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
404 Not Found — sujet inexistant, ou il appartient à une autre organisation. L'API ne confirme jamais qu'un identifiant existe à un appelant qui n'y a pas droit.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.id`	string	Identifiant unique du sujet
`data.name`	string	Nom du sujet, unique dans l'organisation
`data.createdAt`	string	Date de création ISO
`data.updatedAt`	string	Date ISO de la dernière modification
`data.optOutCount`	number	Contacts qui ont refusé ce sujet — perdus si vous le supprimez
`data.campaigns`	array	Campagnes qui le portent, `{id, name, status}`
`data.sequences`	array	Séquences qui le portent, `{id, name, status}`

Exemple de réponse

json

{
  "success": true,
  "data": {
    "id": "7c2e4b19",
    "name": "freelancing",
    "createdAt": "2026-03-04T08:11:00.000Z",
    "updatedAt": "2026-08-01T10:42:19.000Z",
    "optOutCount": 42,
    "campaigns": [
      {"id": "4d19c0a2", "name": "Freelance news", "status": "sent"}
    ],
    "sequences": []
  }
}

Remarques

Les décomptes sont lus en direct. Une campagne créée il y a une seconde apparaît déjà ici — c'est pourquoi une suppression les recalcule plutôt que de se fier à ce que vous avez lu en dernier.
Des campaigns et sequences vides signifient que le sujet peut être supprimé. optOutCount indique ce que cette suppression jetterait.