Where the key stands

GET /api/v1/me The first call of an integration. It answers the one question a key alone cannot: whose data am I about to touch, and with what rights?
FieldDescription
organization.idThe organization the key belongs to — the entire scope of the key
organization.nameIts display name
organization.slugIts slug, the one that appears in the app URLs
organizationRoleThe role the key acts with: owner, admin or member
keyIdThe identifier of the key itself
json
{
  "success": true,
  "data": {
    "organization": {"id": "…", "name": "Acme", "slug": "acme"},
    "organizationRole": "admin",
    "keyId": "…"
  }
}
The value of the key is never returned. keyId names the key, it does not let anyone authenticate with it — a /me response that leaks is an organization name that leaks, not a credential. No endpoint of /api/v1 ever echoes a secret back.
role is the useful half of the answer. A key made by a member can read and render, nothing more; admin is what creating, tagging and sending require — the table is on the API reference. Reading the role before the first write is how an agent finds out it is read-only, rather than by collecting a 403 halfway through a run it cannot undo.

Authorization

Role in the organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERAllowed
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Example

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

Response

  • 200 OK — the call succeeded.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

FieldTypeDescription
successbooleanIndicates if the operation was successful
data.organizationobject{id, name, slug} of the organization the key opens
data.organizationRolestringowner, admin or member — the role its creator holds
data.keyIdstringIdentifier of the key itself
data.sending.readybooleanWhether a campaign can leave right now
data.sending.blockersstring[]Stable machine codes — branch on these, never on a message
data.sending.setupobject{status, provisioning} — the same state the account owner reads on screen

Example response

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

Agent recipe

Two calls turn a bare key into a working context — and tell you what stands in the way before you build anything.
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')

Related