API keys

Create, list and revoke scoped API keys.

Create a key

POST/api/v1/apikeysRequires apikeys:manage
curl -X POST https://mail.example.com/api/v1/apikeys \
  -H "Authorization: Bearer $MAILFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout service",
    "mode": "live",
    "permissions": [
      "emails:send"
    ]
  }'
Body parameters
namestringrequired
2 to 80 characters. Shown in the dashboard.
mode"live" | "test"
Defaults to live. A test key never sends real email. See test mode.
permissionsstring[]
At least one permission. Defaults to ["emails:send", "emails:read"].

Response

201 Created
{
  "data": {
    "id": "c7e0a3b4-51d2-4a37-9f0e-1b6f0c2d4e55",
    "rawKey": "mf_live_Zk3vP0aQ7mXw2Jr9TtYb4LhC8sNdE1uG",
    "prefix": "mf_live_Zk3vP0aQ",
    "name": "Checkout service",
    "permissions": [
      "emails:send"
    ]
  }
}

List keys

GET/api/v1/apikeysRequires apikeys:read
curl https://mail.example.com/api/v1/apikeys \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "data": [
    {
      "id": "c7e0a3b4-51d2-4a37-9f0e-1b6f0c2d4e55",
      "name": "Checkout service",
      "key_prefix": "mf_live_Zk3vP0aQ",
      "permissions": [
        "emails:send"
      ],
      "last_used_at": "2026-11-20T18:04:11.401Z",
      "revoked_at": null,
      "created_at": "2026-11-20T17:58:02.770Z"
    }
  ]
}

Revoke a key

DELETE/api/v1/apikeys/{id}Requires apikeys:manage

Revocation takes effect immediately: the next request with that key gets 401. Revoking a key that is unknown or already revoked returns 404.

curl -X DELETE https://mail.example.com/api/v1/apikeys/c7e0a3b4-51d2-4a37-9f0e-1b6f0c2d4e55 \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "ok": true,
  "id": "c7e0a3b4-51d2-4a37-9f0e-1b6f0c2d4e55"
}