Authentication

Every request carries a secret API key in the Authorization header:

HTTP
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.

Shell
curl https://api.salchimail.com/v1/account \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
JSON
{
  "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

  1. Create a new key in the dashboard.
  2. Deploy it to your application.
  3. 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:

JSON
{
  "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.

View this page as Markdown