Skip to main content

API authentication

The Better Email API uses API keys for server-to-server authentication. Send the key as a bearer token on every request.

Authorization: Bearer <api_key>

Create and manage API keys​

Organization admins manage API keys from Settings -> API Keys.

When a key is valid, every API request is scoped to your organization. A key from one organization cannot read or change recipient fields in another organization.

Keep keys secure​

  • Store API keys in a server-side secret manager or environment variable.
  • Do not expose API keys in frontend code.
  • Do not commit API keys to source control.
  • Revoke and replace a key if it may have been exposed.
  • Use separate keys for separate systems when that makes rotation safer.

Example request​

curl https://app.better.email/api/v1/recipient_fields \
  -H "Authorization: Bearer $BETTER_EMAIL_API_KEY" \
  -H "Accept: application/json"

Authentication failures​

Missing, malformed, invalid, expired, or revoked API keys return 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required."
  }
}

Requests that are authenticated but not allowed return 403 Forbidden. For example, recipient fields created manually or synced from an ESP integration can be listed and read, but cannot be changed through the API.

If authentication is temporarily unavailable, the API returns 503 Service Unavailable:

{
  "error": {
    "code": "api_key_validation_unavailable",
    "message": "Authentication is temporarily unavailable."
  }
}