API Authentication & Permissions
All requests to the Emalc Public Email API must be authenticated using an organization API key passed in the Authorization HTTP header as a Bearer token:
http
Authorization: Bearer em_your_api_key_hereKey Format#
Every API key generated in the Emalc dashboard uses the standard prefix em_ followed by secure high-entropy string tokens (e.g., em_live_8f93a021...).
⚠️ Security Warning:
- Never expose API keys in client-side code (browser JavaScript, public GitHub repositories, mobile applications).
- Store keys securely in server environment variables (
EMALC_API_KEY).- Revoke or rotate keys immediately in your dashboard if compromised.
Provisioning API Keys#
- Navigate to Settings -> API Keys in your Emalc dashboard.
- Click Create API Key.
- Specify a descriptive label (e.g.,
Production Backend - Billing Service). - Select the permissions (scopes) required for this key.
- (Optional) Select specific domain restrictions to scope key sends.
- Click Generate Key and copy your
em_*key. It will only be shown once.
Permission Scopes#
Emalc supports fine-grained scoping so you can adhere to the principle of least privilege:
| Scope | Permission Level | Description |
|---|---|---|
email:send | Write | Grants permission to call POST /api/public/email/send. |
email:read | Read | Grants permission to query GET /api/public/email/:id. |
domain_scope:<domain> | Constraint | Restricts sending to emails matching <domain> (e.g., domain_scope:acme.com). |
full_access | Admin | Full programmatic access across all current and future public API operations. |
Domain Scoping Enforceability#
If an API key configured with domain_scope:acme.com attempts to send an email with from: "noreply@otherdomain.com", the API immediately rejects the request with a 403 FORBIDDEN error:
json
{
"error": "DOMAIN_NOT_ALLOWED",
"message": "API key is not authorized to send from domain 'otherdomain.com'. Allowed domains: acme.com",
"issues": []
}Standard Auth Failure Responses#
Missing or Malformed Token (401 UNAUTHORIZED)#
json
{
"error": "UNAUTHORIZED",
"message": "Missing or invalid Authorization header. Expected format: 'Bearer em_...'",
"issues": []
}Insufficient Scope (403 FORBIDDEN)#
json
{
"error": "FORBIDDEN",
"message": "API key lacks the required scope 'email:send' to perform this action.",
"issues": []
}