API keys
Create, list and revoke scoped API keys.
Create a key
POST
/api/v1/apikeysRequires apikeys:managecurl -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. Atestkey never sends real email. See test mode. permissionsstring[]- At least one permission. Defaults to
["emails:send", "emails:read"].
Response
{
"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:readcurl https://mail.example.com/api/v1/apikeys \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"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:manageRevocation 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"{
"ok": true,
"id": "c7e0a3b4-51d2-4a37-9f0e-1b6f0c2d4e55"
}