Authentication
Every request carries a secret API key in the Authorization header:
Authorization: Bearer sk_live_…Keys
Keys are created in the dashboard at app.salchimail.com. A key is shown once, when you create it, and SalchiMail stores only a hash of it. If you lose a key, create a new one.
| Prefix | Mode | Behaviour |
|---|---|---|
sk_live_ |
Live | Real verifications. Uses credits |
sk_test_ |
Test | Simulated results, no credits. See Test mode |
A key belongs to your organisation, not to a person. Create one key per application or environment and give each a name you will recognise later.
Keep keys on the server
A key is a secret with access to your credits.
- Call the API from your backend. Never ship a key in a web page, a mobile app or a public repository.
- The API does not send CORS headers, so a request made from a browser will fail by design.
- Load the key from an environment variable or a secret manager, not from source code.
Check which key you are using
GET /account returns the organisation, the plan, the limits and the key behind the request. The secret is never returned, only its prefix.
curl https://api.salchimail.com/v1/account \
-H "Authorization: Bearer $SALCHIMAIL_API_KEY"{
"id": "org_7a8b9c0d1e2f3a4b",
"object": "account",
"livemode": true,
"name": "Acme Marketing",
"plan": {
"id": "basic",
"status": "active"
},
"api_key": {
"id": "key_2f3a4b5c6d7e8f9a",
"name": "Production server",
"prefix": "sk_live_a1b2",
"created_at": "2026-11-02T08:15:00Z"
},
"limits": {
"requests_per_minute": 600,
"max_batch_size": 100000,
"max_concurrent_batches": 3,
"modes": [
"basic",
"mailbox"
]
},
"created_at": "2026-11-02T08:10:00Z"
}livemode is false when the request used a sk_test_ key.
Rotate a key
- Create a new key in the dashboard.
- Deploy it to your application.
- Revoke the old key. From that moment it answers
401 revoked_api_key.
Authentication errors
A request without a usable key answers 401 with the header WWW-Authenticate: Bearer:
{
"error": {
"type": "authentication",
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4b5c6d7e8f9a0b1e"
}
}| HTTP | code |
Meaning | What to do |
|---|---|---|---|
| 401 | missing_api_key |
No Authorization: Bearer header |
Send the header on every request |
| 401 | invalid_api_key |
The key does not exist | Check for a truncated or mistyped key |
| 401 | revoked_api_key |
The key was revoked in the dashboard | Use a current key |
| 403 | mode_not_allowed |
The account may not use that mode |
Check limits.modes in GET /account |
| 403 | account_suspended |
The account is suspended | Write to hola@salchimail.com |
The shape of every error is described in Limits and errors.