Skip to main content

​
API keys

Every request to /v1/* endpoints must include an API key as a Bearer token in the Authorization header: 
Authorization: Bearer grl_live_xxxxxxxxxxxx

​
Key format

PrefixModeDescription
grl_live_ProductionFull access, real email delivery
grl_test_TestSandbox mode with reduced limits
Keys are a minimum of 49 characters and match the pattern: 
grl_(live|test)_[a-zA-Z0-9_-]{32,}

​
Security

  • Keys are hashed with SHA-256 before storage — the full key is never stored on our servers.
  • Keys are shown only once at creation time. Store them securely (e.g. environment variable, secret manager).
  • Keys can have an expiration date. Expired keys return 401 expired_api_key.
  • You can revoke a key at any time from the dashboard.

​
Scopes

Each API key is granted specific scopes that control what it can access:
ScopeGrants access to
email:sendPOST /v1/emails, POST /v1/emails/batch
email:readGET /v1/emails, GET /v1/emails/:id, GET /v1/emails/:id/events
domain:manageAll /v1/domains/* endpoints
domain:readGET /v1/domains, GET /v1/domains/:id
stats:readAll /v1/stats/* endpoints
suppression:readGET /v1/suppressions, GET /v1/suppressions/check
suppression:managePOST /v1/suppressions, DELETE /v1/suppressions/:email
privacy:readGET /v1/privacy/*, GET /v1/gdpr/*
privacy:managePOST /v1/privacy/*, POST /v1/gdpr/*, PATCH /v1/privacy/*
If a key lacks a required scope, the API returns: 
{
  "error": {
    "code": "insufficient_permissions",
    "message": "Insufficient permissions. Required scope: email:send",
    "details": { "required": "email:send" },
    "suggestion": "Use an API key with the required scope or contact your administrator"
  }
}

​
Domain-scoped keys

API keys can optionally be scoped to a specific domain. A domain-scoped key can only send emails from that domain and only access that domain’s data. This is useful when you have multiple sending domains and want to limit each integration to its own domain.

​
Test mode

Keys prefixed with grl_test_ enable test mode:
FeatureTest modeProduction
Emails actually delivered✅ Yes (to sandbox domain)✅ Yes
Response headerX-Gorillaa-Test-Mode: true—
Global rate limit500 req/hr10,000 req/hr
Per-key send limit20 emails/hrBased on plan
Daily limit per domain100 emails/dayBased on warming + plan
Lifetime cap per domain300 emails totalUnlimited
Test mode keys are ideal for development and CI/CD pipelines. They use the same API endpoints and response formats as production keys.

​
Example request

curl -X POST https://api.mail.gorillaa.one/v1/emails \
  -H "Authorization: Bearer grl_live_0GyUBWMr1aFAkZdIh1l4n..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": [{ "email": "[email protected]" }],
    "subject": "Test",
    "html": "<p>Hello!</p>"
  }'

​
Best practices

Never hardcode API keys in source code. Store them in environment variables or a secret manager.
export GORILLAA_API_KEY="grl_live_xxxxxxxxxxxx"
Create keys with only the scopes they need. A service that only sends emails should have email:send — not domain:manage.
Set expiration dates and rotate keys periodically. Revoke any keys that may have been exposed.
Use grl_test_ keys for development/staging and grl_live_ keys for production. Never share keys across environments.