Autenticación

Cada petición lleva una clave de API secreta en la cabecera Authorization:

HTTP
Authorization: Bearer sk_live_…

Claves

Las claves se crean en el panel, en app.salchimail.com. Una clave se muestra una sola vez, al crearla, y SalchiMail solo guarda su hash. Si pierdes una clave, crea otra.

Prefijo Modo Comportamiento
sk_live_ Real Verificaciones reales. Consume créditos
sk_test_ Pruebas Resultados simulados, sin créditos. Consulta Entorno de pruebas

Una clave pertenece a tu organización, no a una persona. Crea una clave por aplicación o entorno y ponle un nombre que reconozcas más adelante.

Las claves, siempre en el servidor

Una clave es un secreto con acceso a tus créditos.

  • Llama a la API desde tu backend. Nunca incluyas una clave en una página web, una aplicación móvil o un repositorio público.
  • La API no envía cabeceras CORS, así que una petición hecha desde un navegador fallará por diseño.
  • Carga la clave desde una variable de entorno o un gestor de secretos, no desde el código fuente.

Comprueba qué clave estás usando

GET /account devuelve la organización, el plan, los límites y la clave con la que se hizo la petición. El secreto nunca se devuelve, solo su 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 es false cuando la petición usó una clave sk_test_.

Rota una clave

  1. Crea una clave nueva en el panel.
  2. Despliégala en tu aplicación.
  3. Revoca la clave antigua. Desde ese momento responde 401 revoked_api_key.

Errores de autenticación

Una petición sin una clave utilizable responde 401 con la cabecera WWW-Authenticate: Bearer:

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
HTTP code Significado Qué hacer
401 missing_api_key Falta la cabecera Authorization: Bearer Envía la cabecera en todas las peticiones
401 invalid_api_key La clave no existe Revisa si está cortada o mal copiada
401 revoked_api_key La clave se revocó en el panel Usa una clave vigente
403 mode_not_allowed La cuenta no puede usar ese mode Consulta limits.modes en GET /account
403 account_suspended La cuenta está suspendida Escribe a hola@salchimail.com

La forma de todos los errores se describe en Límites y errores.

Ver esta página en Markdown