Dónde está la clave

GET /api/v1/me La primera llamada de una integración. Responde a la única pregunta que una clave por sí sola no puede responder: ¿de quién son los datos que voy a tocar, y con qué derechos?
CampoDescripción
organization.idLa organización a la que pertenece la clave: todo el alcance de la clave
organization.nameSu nombre visible
organization.slugSu slug, el que aparece en las URL de la app
organizationRoleEl rol con el que actúa la clave: owner, admin o member
keyIdEl identificador de la propia clave
json
{
  "success": true,
  "data": {
    "organization": {"id": "…", "name": "Acme", "slug": "acme"},
    "organizationRole": "admin",
    "keyId": "…"
  }
}
El valor de la clave nunca se devuelve. keyId nombra la clave, no permite autenticarse con ella: una respuesta de /me que se filtra es un nombre de organización que se filtra, no una credencial. Ningún endpoint de /api/v1 devuelve jamás un secreto.
role es la mitad útil de la respuesta. Una clave creada por un member puede leer y renderizar, nada más; admin es lo que exigen crear, etiquetar y enviar; la tabla está en la referencia de la API. Leer el rol antes de la primera escritura es como un agente descubre que es de solo lectura, en lugar de recibir un 403 a mitad de una ejecución que no puede deshacer.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERPermitido
Una clave lleva el rol que su creador tiene en esta organización, nunca un rol sobre AgentsMail en sí. Consulta Claves de API.

Ejemplo

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

Respuesta

  • 200 OK: la llamada se realizó correctamente.
  • 401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
  • 429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

CampoTipoDescripción
successbooleanIndica si la operación se realizó correctamente
data.organizationobject{id, name, slug} de la organización que abre la clave
data.organizationRolestringowner, admin o member: el rol que tiene su creador
data.keyIdstringIdentificador de la propia clave
data.sending.readybooleanSi una campaña puede salir ahora mismo
data.sending.blockersstring[]Códigos de máquina estables: bifurca según ellos, nunca según un mensaje
data.sending.setupobject{status, provisioning}: el mismo estado que el propietario de la cuenta ve en pantalla

Ejemplo de respuesta

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

Receta para agentes

Dos llamadas convierten una clave sin más en un contexto de trabajo, y te dicen qué se interpone antes de que construyas nada.
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')

Relacionado