API keys

An API key lets a script — or an agent — do over HTTP what a person does in the interface. You create one from your account, and it is shown once: copy it then, or create another.

What a key opens

A key belongs to one organization, and that organization is its whole world. It cannot see or touch anything outside it, and there is no key that spans two. More importantly, a key is not a second identity with its own powers. It carries the rights of the member who created it: a key made by an administrator can write, a key made by a member can only read. Nothing is reachable through the API that its creator could not do by hand.
A key stops working when its owner leaves the organization. It answers 401 from that moment, exactly as if revoked — no orphan access survives a departure. Revoking a departed colleague's key is housekeeping, not a security fix.

How long it lasts

When you create a key you choose whether it ends: leave Never expires ticked and it stays valid until you revoke it, or untick it and pick a date — anywhere from a day to a year out. The Expires column on the API keys screen tells you which is which. Once that date passes the key answers 401, exactly as a revoked one does.

Using one

Every request carries it in the x-api-key header:
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/tags"
One call tells a key where it stands — which organization it opens, with which role, and which lists exist behind it. That is the whole bootstrap: see Discovery.

Good practice

  • One key per use. A key per script, per agent, per environment. Revoking one then costs nothing to the others.
  • Name them for what they do, not for who you are — the name is what you will read when deciding whether to revoke.
  • Imported contacts record the name of the key that created them, so a well-named key is also how you trace an audience back to its origin months later.

What it implies elsewhere

Revoking a key is immediate and irreversible. Nothing it created is undone — the contacts, templates and campaigns it made stay exactly as they are. The full reference — the response envelope, the status codes, who may call what — is the API section.