API Keys, Headers & Scopes
Every request to the Envelark API must be authenticated using an active production or sandbox API key. Keys are provisioned with granular capability scopes to enforce the principle of least privilege.
1. Key Format & Generation
Envelark API keys are cryptographically generated using 48 lowercase hexadecimal characters (24 random bytes) from secure entropy via Crypto::generateApiKey(). Production keys begin with the prefix elv_live_ followed by the hex secret. For backward compatibility with earlier integrations, the authentication validator (Auth::attemptApiKey()) also accepts the legacy env_live_ prefix alias and normalizes between both prefixes during lookup.
A standard production key consists of the 9-character prefix (elv_live_, or the legacy alias env_live_) concatenated with 48 hexadecimal characters ([0-9a-f]), or 32 hexadecimal characters for initial seeded workspace keys. In all code samples below, replace the placeholder YOUR_API_KEY with your workspace credential.
How to Create API Keys
- Log into your Envelark workspace and navigate to the Developer console (sign in) (or Superadmin portal under
/admin). - Under Active API Credentials, your default live production key is ready for immediate relay.
- To configure new application credentials or custom webhook listeners, register a developer client with your desired capability scopes.
2. Authentication Header
Pass your API key using the standard HTTP Authorization header with the Bearer scheme. Alternatively, the custom headers X-Envelark-Api-Key and X-Api-Key are accepted by ApiController::authenticateApiRequest():
# Recommended: Bearer token header
Authorization: Bearer YOUR_API_KEY
# Alternate 1: Envelark custom API key header
X-Envelark-Api-Key: YOUR_API_KEY
# Alternate 2: Standard custom API key header alias
X-Api-Key: YOUR_API_KEY
3. Verified Capability Scopes
Every scope corresponds directly to capability definitions in the platform backend. The following scopes exist in the codebase:
| Scope Name | Granted Capabilities |
|---|---|
mail.read |
Read mailboxes, query email threads, fetch thread messages, read smart category classifications, and view folder states. |
mail.write |
Dispatch outbound email, execute transactional email sending, mutate thread workflow status, star/archive threads, and assign tickets. |
mail.send |
Permission to invoke SMTP/Relay transactional email sending (aliased to mail.write for transactional pipelines). |
files.read |
Inspect attachment metadata, verify SHA-256 fingerprints, and download files from the Elept cloud storage vault. |
files.write |
Authorize file uploads to Elept Cloud, create persistent live ZIP packages (Elept Rooms), and heal storage references. |
templates.read |
Fetch standard SaaS built-in developer templates (password reset, account verify, receipt, security alert) and custom workspace templates. |
templates.write |
Create, edit, compile dynamic preview variables, and delete transactional HTML templates. |
webhooks.manage |
Register destination webhook URLs, rotate HMAC SHA-256 secrets, and trigger synthetic test webhook deliveries. |
4. Rate Limiting & Error Responses
To ensure high availability and prevent resource exhaustion, the API controller enforces an algorithmic sliding-window rate limit using RateLimiter::enforce('api_v1', $clientIdentifier, 120, 60):
- Ceiling:
120 requestsper60-second windowper client identifier. - Exceeded Response: HTTP
429 Too Many Requestswith structured error envelope viaResponse::error().
// HTTP 429 Too Many Requests Response
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Too Many Requests. Rate limit exceeded.",
"details": []
}
}
Standard API Error Codes
All API error responses use the standard envelope {"success": false, "error": {"code": "...", "message": "...", "details": [...]}} emitted by Response::error() (app/core/Response.php:27-37):
| Error Code | HTTP Status | Source (file:line) |
Description |
|---|---|---|---|
empty_body |
400 |
ApiController.php:275, 338 |
Empty request body on inbound webhook endpoint. |
invalid_signature |
400 |
ApiController.php:298 |
Inbound webhook HMAC signature verification failed. |
webhook_error |
400 |
ApiController.php:305 |
Inbound webhook payload processing error. |
webhook_verification_failed |
400 |
ApiController.php:353 |
Inbound Elept webhook signature verification failed. |
update_failed |
400 |
ApiController.php:716 |
Thread category mutation failed. |
unauthorized |
401 |
ApiController.php:51, 65 |
Invalid, expired, or missing API key / bearer token. |
missing_signature |
401 |
ApiController.php:293, 344 |
Missing webhook signature header on inbound webhook endpoint. |
forbidden |
403 |
ApiController.php:74, 114, 161, 167, 432 |
Access to specified mailbox/thread denied or protected system template. |
not_found |
404 |
ApiController.php:129, 396 |
Requested thread or template ID/slug does not exist. |
route_not_found |
404 |
Router.php:129 |
Requested API endpoint path or HTTP method does not match any registered route. |
invalid_input |
422 |
ApiController.php:146, 185, 368, 421, 572 |
Missing or invalid required request parameters (e.g., to, subject, name, body_html, or content). |
delivery_failed |
422 |
ApiController.php:456 |
Transactional template validation failed (to and template/html required) or message dispatch failed. |
rate_limit_exceeded |
429 |
ApiController.php:31 |
Client exceeded 120 requests per 60-second window. |
internal_server_error |
500 |
p/index.php:66 |
Unhandled server exception on an /api/* route. |
5. Real Endpoint Examples
A. Fetch Mailboxes (GET /api/v1/mailboxes)
curl -X GET https://envelark.com/api/v1/mailboxes \
-H "Authorization: Bearer YOUR_API_KEY"
Response (HTTP 200 OK — serialized by MailboxService::getUserMailboxes() / getSampleMailboxes(), app/services/MailboxService.php:66-77, 1189-1233):
{
"success": true,
"message": "OK",
"data": [
{
"id": 1,
"organization_id": 1,
"name": "Support Team",
"email_address": "support@example.com",
"type": "hosted",
"provider": "envelark_hosted",
"color": "#0EA5E9",
"unread_count": 3,
"sync_status": "healthy",
"last_synced_at": "2026-10-23 12:00:00"
}
]
}
B. Dispatch Transactional Template (POST /api/v1/send)
curl -X POST https://envelark.com/api/v1/send \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "password_reset",
"to": "alex@example.com",
"sender_name": "Acme Security",
"sender_email": "security@example.com",
"reply_to": "support@example.com",
"variables": {
"user_name": "Alex",
"reset_url": "https://example.com/auth/reset?token=xyz987",
"expiry_minutes": "30"
},
"branding": {
"company_name": "Acme Corp",
"primary_color": "#152E22"
}
}'
Response (HTTP 201 Created — serialized by TemplateService::sendTransactional(), app/services/TemplateService.php:771-784, and ApiController::sendTransactional(), app/controllers/Api/ApiController.php:438-461):
{
"success": true,
"message": "Transactional email dispatched.",
"data": {
"success": true,
"message_id": "<3b68bc0974099c381f845e53463943c3@envelark.com>",
"to": "alex@example.com",
"subject": "Reset your password for Acme Corp",
"template": "password_reset",
"sent_at": "2026-10-23 12:00:00",
"provider": "envelark_transactional_relay"
}
}