Credentials & Permissions

Credentials are API keys that authenticate your requests to the Emitlo API and SMTP relay. Each credential is scoped to a specific sending domain and has a set of permissions.

Permissions

Permission	What it allows
`send`	Send emails via `POST /api/v1/messages` and batch
`stats`	Read message status, events, and statistics
`admin`	Manage domains, credentials, suppressions, and webhooks

A credential can have multiple permissions. Common combinations:

Use case	Permissions
Backend email sending	`send`
Monitoring / analytics	`stats`
Full API access	`send`, `stats`, `admin`
SMTP relay	`send` (username + secret used for SMTP AUTH)

Creating a credential

Go to Dashboard → Credentials
Click Create Credential
Select the sending domain this credential is scoped to
Enter a label (e.g. “Production Backend”)
Select the required permissions
Click Create

Using your credential

REST API

Include the secret key as a Bearer token:

Authorization: Bearer YOUR_SECRET_KEY

SMTP relay

Use the credential username and secret key for SMTP AUTH PLAIN:

Host:     api.emitlo.com
Port:     587
Security: STARTTLS
Username: YOUR_CREDENTIAL_USERNAME
Password: YOUR_SECRET_KEY

See SMTP Integration for full details.

Security best practices

One credential per service — create separate credentials for each application or environment (production, staging, etc.)
Minimum permissions — only grant the permissions each service actually needs
Never commit keys — use environment variables or a secrets manager
Rotate regularly — revoke and recreate credentials periodically
Revoke immediately if a key is compromised

Credential statuses

Status	Description
`active`	Credential is usable
`suspended (DNS)`	Domain failed DNS validation; auto-reactivated when domain recovers
`suspended (SPAM)`	Organization exceeded bounce/complaint thresholds
`revoked`	Manually revoked; permanent