Platform
Accounts, API keys and pods
One Pidgeon account holds your inboxes, your team, your billing and your reputation. Your servers call the API with an account’s API key, and each key has an access level that decides what it may do. Pods divide an account into tenants, so a platform keeps each user’s inboxes, domains and agents apart.
Accounts and the team
- An account is a person’s or a company’s. People sign in by email link or Google.
- The owner invites people by address; nobody joins until they accept, signed in with that address. The owner can withdraw an invitation and remove members; a member can leave. A person belongs to one account. Teams are free.
- The verification level, the reputation and billing belong to the account, never to a member.
API keys
Make a key in the dashboard, under API keys in the menu. It looks like pgn_ and 32 characters, and it is shown once: Pidgeon keeps only its SHA-256. Send it as a bearer token, from a server, never from a browser or an app.
curl https://pidgeon.ai/v1/pods -H "Authorization: Bearer $PIDGEON_API_KEY"Access levels
Each level includes the ones before it. A key below what a call needs gets 403 forbidden, naming the level.
| Access | May | For example |
|---|---|---|
read | Look | Every GET: inboxes, mail, conversations, events. |
draft | Prepare without effect | Writing Email drafts and asking a person to approve them; never sending. |
send | Act on somebody else | Sending mail, mandates. |
admin | Change the account’s setup | Inboxes, domains, pods, webhooks, agent keys, sites. |
The dashboard offers all four: Read, Draft, Send and Admin. Revoke a key in the same place; it stops at once.
Keys from the API
An agent setting Pidgeon up can make its own keys: POST /v1/keys with an admin key of the whole account (or the MCP server’s create_api_key). A new key is never stronger than the one making it, and a test key makes only test keys. The key is in the answer once: put it straight where it will live. GET /v1/keys lists them without the keys; DELETE /v1/keys/{id} revokes one.
curl https://pidgeon.ai/v1/keys \
-H "Authorization: Bearer $PIDGEON_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "support agent", "access": "draft"}'Test keys
Choose Test as the mode when you make a key, and it looks like pgn_test_ and 32 characters. A test key does everything a live key does, except where it is marked test:
- None of its mail leaves Pidgeon. See mail that never leaves.
- A mandate it asks for is a test mandate: it needs no verified domain, and every token under it says
test: true, for a site to refuse in production. See testing mandates.
Use one in CI, in staging, or wherever an agent is being built.
Rate limit
600 requests a minute per key, over a sliding window. Past it: 429 rate_limited with Retry-After in seconds.
Every answer to a key says where it stands, in the IETF fields RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers) and in the older RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset most clients read:
RateLimit-Policy: "per-key";q=600;w=60
RateLimit: "per-key";r=597;t=42
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42r and RateLimit-Remaining are the requests left; t and RateLimit-Reset the seconds until the window refills. Sending has limits of its own, per account: sending limits.
Idempotency
A call that sends mail or makes something takes an Idempotency-Key header, so a retry after a timeout or a dropped connection is never done twice: POST /v1/email/inboxes/{id}/messages, POST /v1/email/drafts/{id}/send, POST /v1/email/inboxes/{id}/drafts, POST /v1/email/inboxes and POST /v1/pods.
- The key is any 1 to 255 printable characters unique to the request: a UUID, or your own id for the message.
- The first call with a key is done, and its answer kept 24 hours. A retry with the same key and the same body, from the same API key, gets that answer again, with
Idempotent-Replayed: true, and nothing is sent or made. - The same key with a different body, or from another key of the account, is
422 idempotency_key_reused. A retry while the first call is still running is409 idempotency_in_progress, withRetry-After. - An answer of
429or5xxis not kept, since nothing was done: retry with the same key.
Pods
A pod is a tenant inside an account: a platform gives one to each of its users (Platforms). Inboxes, domains, agents, sign-in sites and webhook endpoints each live in one. Every account has a default pod, which is where anything made without a pod_id goes. Billing, the team, KYB and reputation stay with the account.
A key of one pod reaches only its own pod: its agents, inboxes, domains, webhook endpoints and events. It makes inboxes on, and sends from, its own pod’s domains and pidgeon.email only, so one customer’s pod never mails as another’s domain.
# List (read access)
curl https://pidgeon.ai/v1/pods -H "Authorization: Bearer $PIDGEON_API_KEY"
# Create (admin access, a key of the whole account)
curl https://pidgeon.ai/v1/pods \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Customer: Northwind"}'
# Rename (admin access, a key of the whole account)
curl -X PATCH https://pidgeon.ai/v1/pods/1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6 \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Customer: Northwind Labs"}'
# Move an agent (with its addresses and their mail) into a pod
curl https://pidgeon.ai/v1/pods/1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6/move \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "agent", "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a"}'
# Remove an empty pod (admin access, a key of the whole account)
curl -X DELETE https://pidgeon.ai/v1/pods/1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6 -H "Authorization: Bearer $PIDGEON_API_KEY"A pod’s name is up to 80 characters and unique in the account. Pass pod_id when registering an agent or creating an inbox or an Auth site to put it in a pod. Renaming one (PATCH, name) answers the pod and records pod.renamed; its id and everything in it stay. POST /v1/pods/{id}/move with type (agent, inbox, domain, webhook or site) and id (a site’s client id) moves that thing into the pod and records pod.item_moved: an agent takes its addresses and all their mail with it, and an address that belongs to an agent moves only with it (409). API keys do not move: a key’s reach is chosen when it is made. Keys of the pod a thing left stop reaching it. Moving takes an admin key of the whole account. Removing a pod answers 204 and records pod.removed; the default pod cannot be removed (403), and a pod with agents, domains or webhook endpoints in it answers 409 until they are removed.
Keys of one pod
A key can reach one pod instead of the whole account: it then makes inboxes, reads and sends their mail, adds webhook endpoints, lists events, publishes and revokes agent keys and makes sites only within that pod, and cannot make or remove pods or make keys.
In the dashboard, Account → Pods lists the account’s pods, and its owner makes, renames and removes them there. Once there are two, a switcher at the top shows one pod or all, and making a key asks what it reaches: the whole account, or one pod.
Keys of some inboxes
A key from the old Pidgeon that reached only some addresses reaches only those inboxes here. It lists and reads their mail, conversations and events, and sends from them; every other call answers 401. Keys made in the dashboard reach the whole account.
Apps that connect with OAuth
An app can ask a person for access instead of an API key, by the authorization code flow with PKCE. The authorization server’s metadata is at /.well-known/oauth-authorization-server; apps identify themselves with a client metadata document (an https client_id) or register at /oauth/register (RFC 7591). The person chooses the access level on the consent screen, never more than the app asked for (the scopes are read, draft, send, admin).
- Access tokens are
pgn_oat_…, for an hour, and work on/v1like the API key they stand for. - Refresh tokens are
pgn_ort_…and turn over on every use; one used twice ends the connection. An app registered as an Auth site sends its client secret with the refresh, as at the code exchange. - Connected apps, in the dashboard’s menu, lists them and disconnects them.
POST /oauth/revokeends one from the app’s side. - Every
401from/v1carriesWWW-Authenticate: Bearer resource_metadata="https://pidgeon.ai/.well-known/oauth-protected-resource".