Où se situe la clé

GET /api/v1/me Le premier appel d'une intégration. Il répond à la seule question qu'une clé seule ne résout pas : à qui sont les données que je m'apprête à toucher, et avec quels droits ?
ChampDescription
organization.idL'organisation à laquelle appartient la clé — tout le périmètre de la clé
organization.nameSon nom affiché
organization.slugSon slug, celui qui apparaît dans les URL de l'application
organizationRoleLe rôle avec lequel la clé agit : owner, admin ou member
keyIdL'identifiant de la clé elle-même
json
{
  "success": true,
  "data": {
    "organization": {"id": "…", "name": "Acme", "slug": "acme"},
    "organizationRole": "admin",
    "keyId": "…"
  }
}
La valeur de la clé n'est jamais renvoyée. keyId nomme la clé, il ne permet à personne de s'authentifier avec — une réponse de /me qui fuite, c'est un nom d'organisation qui fuite, pas un identifiant de connexion. Aucun endpoint de /api/v1 ne renvoie jamais un secret.
role est la moitié utile de la réponse. Une clé créée par un member peut lire et faire des rendus, rien de plus ; admin est ce qu'exigent la création, le tag et l'envoi — le tableau est dans la référence de l'API. Lire le rôle avant la première écriture, c'est ainsi qu'un agent découvre qu'il est en lecture seule, plutôt qu'en récoltant un 403 au milieu d'une exécution qu'il ne peut pas annuler.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERAutorisé
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.

Exemple

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

Réponse

  • 200 OK — l'appel a réussi.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

ChampTypeDescription
successbooleanIndique si l'opération a réussi
data.organizationobject{id, name, slug} de l'organisation que la clé ouvre
data.organizationRolestringowner, admin ou member — le rôle que détient son créateur
data.keyIdstringIdentifiant de la clé elle-même
data.sending.readybooleanIndique si une campagne peut partir tout de suite
data.sending.blockersstring[]Codes machine stables — branchez-vous sur eux, jamais sur un message
data.sending.setupobject{status, provisioning} — le même état que le propriétaire du compte lit à l'écran

Exemple de réponse

json
{
  "success": true,
  "data": {
    "organization": {
      "id": "a19f4c02",
      "name": "Example",
      "slug": "example"
    },
    "organizationRole": "admin",
    "keyId": "f3c7d221",
    "sending": {
      "ready": true,
      "blockers": [],
      "setup": {
        "status": "verified",
        "provisioning": "provisioned"
      }
    }
  }
}

Recette pour agent

Deux appels transforment une clé nue en contexte de travail — et vous disent ce qui fait obstacle avant que vous ne construisiez quoi que ce soit.
js
const base = 'https://www.agentsmail.io/api/v1'
const headers = {'x-api-key': process.env.AGENTMAIL_API_KEY}

const me = await (await fetch(`${base}/me`, {headers})).json()

if (!me.data.sending.ready) {
  // `blockers` is a stable vocabulary — branch on it, never on a message
  throw new Error(`cannot send yet: ${me.data.sending.blockers.join(', ')}`)
}

const lists = await (await fetch(`${base}/lists`, {headers})).json()
const newsletter = lists.data.find((list) => list.name === 'Newsletter')

Voir aussi