Authentication

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

Prefix	Mode	Description
`grl_live_`	Production	Full access, real email delivery
`grl_test_`	Test	Sandbox 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:

Scope	Grants access to
`email:send`	`POST /v1/emails`, `POST /v1/emails/batch`
`email:read`	`GET /v1/emails`, `GET /v1/emails/:id`, `GET /v1/emails/:id/events`
`domain:manage`	All `/v1/domains/*` endpoints
`domain:read`	`GET /v1/domains`, `GET /v1/domains/:id`
`stats:read`	All `/v1/stats/*` endpoints
`suppression:read`	`GET /v1/suppressions`, `GET /v1/suppressions/check`
`suppression:manage`	`POST /v1/suppressions`, `DELETE /v1/suppressions/:email`
`privacy:read`	`GET /v1/privacy/`, `GET /v1/gdpr/`
`privacy:manage`	`POST /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:

Feature	Test mode	Production
Emails actually delivered	✅ Yes (to sandbox domain)	✅ Yes
Response header	`X-Gorillaa-Test-Mode: true`	—
Global rate limit	500 req/hr	10,000 req/hr
Per-key send limit	20 emails/hr	Based on plan
Daily limit per domain	100 emails/day	Based on warming + plan
Lifetime cap per domain	300 emails total	Unlimited

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

Use environment variables

Never hardcode API keys in source code. Store them in environment variables or a secret manager.

export GORILLAA_API_KEY="grl_live_xxxxxxxxxxxx"

Use minimum scopes

Create keys with only the scopes they need. A service that only sends emails should have email:send — not domain:manage.

Rotate keys regularly

Set expiration dates and rotate keys periodically. Revoke any keys that may have been exposed.

Use separate keys per environment

Use grl_test_ keys for development/staging and grl_live_ keys for production. Never share keys across environments.

Get Started

Guides

Reference

API keys

Key format

Security

Scopes

Domain-scoped keys

Test mode

Example request

Best practices

​API keys

​Key format

​Security

​Scopes

​Domain-scoped keys

​Test mode

​Example request

​Best practices

API keys

Key format

Security

Scopes

Domain-scoped keys

Test mode

Example request

Best practices