SMTP Credentials & Rotation

To secure your testing pipelines and avoid shared static secrets, Emailens allows you to generate individual SMTP credentials per inbox, service, or developer.

Credential Structure & Security

When you create a credential in an SMTP sandbox inbox:

• Username: Generated with the prefix esmtp_ (e.g. esmtp_clx9abc123_staging).
• Password: 32-character cryptographically secure pseudorandom token.
• Storage: Emailens never stores your raw SMTP password. It is hashed using SHA-256 before being committed to PostgreSQL.
• Security In Transit: Connections presenting esmtp_ credentials must establish TLS/STARTTLS encryption. Plaintext authentication attempts without TLS are immediately terminated with an error.

Generating Credentials

You can generate credentials via the web UI or REST API:

Via Dashboard

1. Open your SMTP Sandbox inbox in app.emailens.dev/dashboard/sandbox.
2. Expand the SMTP Relay Configuration panel.
3. Click Generate credential.
4. Give it a descriptive name (e.g., Staging Auth Microservice or GitHub CI Runner).
5. Copy the generated password immediately (it is only shown once).

Via REST API

curl -X POST https://app.emailens.dev/api/sandbox/smtp/credentials \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inboxId": "clx9inbox123",
    "name": "Staging Backend Worker"
  }'

Response:

{
  "credential": {
    "id": "cred_abc123",
    "inboxId": "clx9inbox123",
    "name": "Staging Backend Worker",
    "username": "esmtp_worker_clx9",
    "password": "sec_f893a74910b48f93e...",
    "createdAt": "2026-10-08T12:00:00Z"
  }
}

Zero-Downtime Credential Rotation

Credential rotation allows you to replace an existing credential when an employee leaves, an API token expires, or during periodic security audits:

How It Works

1. When you trigger rotation on a credential, Emailens generates a fresh username and password while tracking the rotation event.
2. In the dashboard, click Rotate next to any credential.
3. A confirmation modal provides the new username and secret token.
4. Update your application's environment variables (EMAILENS_SMTP_PASS) and restart your service.

Rotating via REST API

curl -X POST https://app.emailens.dev/api/sandbox/smtp/credentials/cred_abc123/rotate \
  -H "Authorization: Bearer ek_live_..."

Revoking Credentials

If a credential is compromised or no longer needed, revoke it immediately:

• In the dashboard, click Revoke next to the credential row.
• Or send a DELETE request:

curl -X DELETE https://app.emailens.dev/api/sandbox/smtp/credentials/cred_abc123 \
  -H "Authorization: Bearer ek_live_..."

Any subsequent SMTP handshake attempting authentication with the revoked credentials will immediately fail with 535 5.7.8 Invalid SMTP username or password.