KoltrixProtecting email API keys: scopes, rotation, leak response
An email API key is the power to send as your domain. Scope keys narrowly, store them safely, rotate them on a schedule and respond fast to leaks.
On this page(8 sections)
- What an attacker can do with a leaked key
- Scope every key narrowly
- Store keys where they cannot leak casually
- Never in client-side code
- Never in source control
- In a secret manager or environment
- Not in logs or error reports
- Rotate on a schedule
- Detect misuse early
- When a key leaks
- A practical review checklist
- Bottom line
An email API key is not just a credential for a service. It is the ability to send authenticated mail as your domain, with your DKIM signature and your reputation attached.
Treat it with the same care as a production database password, because the damage from a leak is just as public.
What an attacker can do with a leaked key
Depending on the provider and the key's permissions, a leaked email API key can let someone:
- Send phishing or spam that passes SPF, DKIM and DMARC for your domain.
- Read message logs, recipient lists and sometimes message content.
- Change webhook endpoints, redirecting delivery and bounce events to themselves.
- Add or modify sending domains, or create additional keys for persistence.
- Exhaust your sending quota and get your account suspended by the provider.
The reputation damage outlasts the incident. Mailbox providers remember complaint spikes and spam traps hit under your domain, and recovery can take weeks.
Scope every key narrowly
The single most effective control is giving each key only the permissions its job requires. Many email providers support scoped keys; use them.
| Key use | Permissions it needs | Permissions it should not have |
|---|---|---|
| Application sending password resets | Send | Read logs, manage domains, manage keys |
| Analytics job pulling delivery stats | Read events or stats | Send, manage anything |
| Webhook setup script | Manage webhooks | Send |
| Admin automation | Manage domains and keys | Used by application code |
For example, Koltrix API keys carry permission scopes, and the send endpoint rejects a key that lacks the send permission. Whatever provider you use, check which scopes exist and create separate keys for separate jobs.
Beyond permissions, look for other ways to narrow a key's reach:
- Restrict sending addresses or domains where the provider allows, so a key for notifications cannot send as
[email protected]. - Restrict source IPs for server-side keys, if supported. A key that only works from your production network is far less useful to an attacker.
- Use separate keys per environment. Staging and production should never share a key.
- Use separate keys per service. When one service leaks its key, you rotate one key, not every integration you have.
Store keys where they cannot leak casually
Never in client-side code
An email API key in a browser bundle or mobile app is public. Anyone can extract it. Sending must happen from your servers; the client calls your backend, which decides whether to send.
Never in source control
Keys committed to a repository, even a private one, spread to every clone, fork, CI cache and backup. Enable secret scanning on your repositories, and add pre-commit hooks that catch common key formats. Many email providers use a recognizable key prefix, which makes automated detection reliable.
In a secret manager or environment
Load keys at runtime from a secret manager or the deployment platform's secret store. Restrict who can read production secrets, and log access.
Not in logs or error reports
Make sure your HTTP client does not log Authorization headers, and that error tracking tools scrub them. A key in a log aggregator is readable by everyone with log access.
Rotate on a schedule
Rotation limits how long a silently leaked key remains useful, and keeps the rotation procedure working for the day you need it in a hurry.
A zero-downtime rotation:
- Create a new key with the same scopes.
- Deploy it to the service alongside the old one, or replace the old one in the secret store and roll the service.
- Confirm traffic is using the new key, through provider logs or your own metrics.
- Revoke the old key.
- Record the rotation date and owner.
Rotate at least annually, whenever someone with access to the key leaves the team, and immediately on any suspicion of exposure.
Detect misuse early
- Monitor send volume per key. A key that normally sends a few hundred messages an hour and suddenly sends thousands is a strong signal.
- Watch bounce and complaint rates per key. Spam sent with a stolen key often produces a burst of hard bounces.
- Alert on configuration changes. New domains, new keys and changed webhook URLs should notify a human.
- Review provider audit logs, if available, for API calls from unfamiliar IPs.
When a key leaks
Speed matters more than root cause analysis in the first hour.
- Revoke the key immediately. Accept that the service using it will fail until a new key is deployed; that is better than continued abuse.
- Issue a new key with the same narrow scopes and deploy it.
- Check what the attacker did. Review sends, configuration changes, new keys and webhook changes made during the exposure window. Revoke any keys or webhooks you did not create.
- Purge queued messages sent by the attacker, if your provider allows.
- Find the leak. Repository history, client bundles, logs, tickets or a compromised machine. Remove the key from wherever it appeared, including git history if it was committed, and remember that removing it from history does not un-leak it.
- Watch reputation for the following days: complaint rates, postmaster dashboards and blocklists.
A practical review checklist
- Each service and environment has its own key.
- Each key has the minimum scopes required.
- No keys exist in client-side code, repositories, logs or tickets.
- Secret scanning is enabled on all repositories.
- Keys are stored in a secret manager with restricted access.
- Rotation happens on a schedule and after staff changes.
- Per-key volume, bounce and complaint alerts are in place.
- A written leak-response procedure exists, and someone has practiced it.
Bottom line
An email API key is a signing pen for your domain. Scope it to one job, keep it on the server, store it in a secret manager, rotate it regularly and watch how it is used. When one leaks, revoke first and investigate second.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
