Añadir una dirección de correo electrónico secundaria no verificada a un usuario

POST /v1/users/{user_id}/emails · permiso users:write

Añade al usuario una dirección de correo electrónico secundaria no verificada. La dirección se normaliza antes de almacenarse. Si el usuario ya tiene la misma dirección, no se escribe ninguna fila y se devuelve la fila existente (que puede estar verificada o ser la principal), por lo que repetir la solicitud es seguro. Se escribe una nueva fila en el registro de auditoría de gestión como user.email_added, con la clave de API como actor; la dirección en sí no se escribe en el registro de auditoría. Para verificar la dirección, envíe un correo de verificación con POST /v1/users/{user_id}/emails/{email_id}:send-verification o márquela como verificada con :verify.

Solicitud

Parámetro En Obligatorio Descripción
user_id ruta sí ID del usuario, con el prefijo usr_.
Campo Tipo Obligatorio Descripción
email cadena sí La dirección, de como máximo 320 caracteres.

Respuesta

201 Created con la fila del correo electrónico. Sin el permiso users:read_pii, la dirección aparece enmascarada (a***@e***.com).

{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": false,
  "primary": false,
  "created_at": "2026-01-15T09:30:00Z"
}

Errores

Cada error es un cuerpo application/problem+json con un code estable.

HTTP code Cuándo
400 malformed_request, unknown_field El cuerpo no es JSON válido o tiene un campo desconocido.
409 conflict La dirección está verificada en otro usuario de este entorno (errors[]: /email, email_taken).
409 email_limit_reached El usuario ya tiene 10 direcciones.
415 unsupported_media_type El cuerpo se envió sin Content-Type: application/json.
422 validation_failed email falta, está vacío, supera los 320 caracteres, no es una dirección válida o tiene un tipo incorrecto.
404 not_found El usuario no existe en este entorno, está en proceso de eliminación o el ID tiene un formato incorrecto.
401 unauthenticated La clave de API falta, no es válida o fue revocada.
403 insufficient_permissions La clave no tiene el permiso users:write.
429 rate_limited Se superó el límite de frecuencia; respete Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente; reintente más tarde.

Ejemplo

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com"}'

Datos personales

Este endpoint contiene datos personales: perfil del usuario final. Datos personales en las API de KeenAuth describe qué se almacena, durante cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.