Autenticación

MailLand admite dos métodos de autenticación: tokens Bearer (JWT) para sesiones de usuario y claves API para la integración servidor a servidor. Todas las solicitudes a la API requieren autenticación mediante el encabezado Authorization.

Métodos de autenticación

Método	Encabezado	Caso de uso
Token Bearer	`Authorization: Bearer <token>`	Sesiones de usuario, panel de control
Clave API	`X-API-Key: <key>`	Servidor a servidor, automatización

Registro

POST https://api.mail.land/v1/auth/register

Solicitud de registro

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd!",
  "fullName": "John Doe",
  "companyName": "My Company"
}

curl -X POST https://api.mail.land/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!",
    "fullName": "John Doe",
    "companyName": "My Company"
  }'

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de correo electrónico
`password`	string	Sí	Contraseña (8–128 caracteres; requiere una mayúscula, una minúscula, un dígito y un carácter especial)
`fullName`	string	No	Nombre completo
`companyName`	string	No	Nombre de la empresa / espacio de trabajo

Los campos desconocidos (como un tenantName enviado por error) se descartan silenciosamente.

Respuesta de registro

{
  "requiresEmailVerification": true,
  "verificationTicket": "vt_abc123...",
  "maskedEmail": "u***@example.com"
}

El estado de la respuesta es 201.

Tras el registro, verifique la dirección de correo electrónico antes de iniciar sesión.

Verificación de correo electrónico

El registro envía por correo un código de 6 dígitos. Llame a POST /v1/auth/verify-email-ticket con { "ticket": "<verificationTicket>", "code": "123456" }; si tiene éxito, devuelve la respuesta de tokens de inicio de sesión.

POST https://api.mail.land/v1/auth/verify-email-ticket

Solicitud de verificación de correo

{
  "ticket": "vt_abc123...",
  "code": "123456"
}

Verify email

curl -X POST https://api.mail.land/v1/auth/verify-email-ticket \
  -H "Content-Type: application/json" \
  -d '{"ticket": "vt_abc123...", "code": "123456"}'

Reenvíe el correo de verificación: llame a POST /v1/auth/resend-verification-ticket con { "ticket": "..." }. Está limitado por frecuencia y devuelve un nuevo ticket.

POST https://api.mail.land/v1/auth/resend-verification-ticket

Solicitud de reenvío de verificación

{
  "ticket": "vt_abc123..."
}

Resend verification

curl -X POST https://api.mail.land/v1/auth/resend-verification-ticket \
  -H "Content-Type: application/json" \
  -d '{"ticket": "vt_abc123..."}'

Inicio de sesión

POST https://api.mail.land/v1/auth/login

Solicitud de inicio de sesión

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!"
  }'

Respuesta

La respuesta de inicio de sesión varía según el estado de la cuenta:

Inicio de sesión exitoso:

Respuesta de inicio de sesión

{
  "userId": "v4j2x7n1m9k5p3",
  "email": "[email protected]",
  "fullName": "John Doe",
  "avatarUrl": null,
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_a1b2c3d4e5...",
  "expiresAt": "2026-09-25T13:00:00Z",
  "requiresTwoFactor": false,
  "twoFactorChallengeId": null,
  "tenantCount": 1,
  "activeTenantId": "k3m9x2p7qw4rtz",
  "activeTenantName": "My Company",
  "requiresEmailVerification": false,
  "verificationTicket": null,
  "maskedEmail": null
}

No hay un objeto user ni un campo role en la respuesta. Una cuenta no verificada recibe 200 con requiresEmailVerification: true y un verificationTicket, no un error.

Se requiere autenticación de dos factores:

Respuesta de 2FA requerida

{
  "accessToken": null,
  "refreshToken": null,
  "requiresTwoFactor": true,
  "twoFactorChallengeId": "2fa_challenge_abc123"
}

Cuando requiresTwoFactor es true, complete la verificación 2FA antes de recibir los tokens.

Actualización de token

Los tokens de acceso expiran después de 60 minutos. Use el token de actualización para obtener un nuevo token de acceso:

POST https://api.mail.land/v1/auth/refresh-token

Solicitud de actualización de token

{
  "refreshToken": "rt_a1b2c3d4e5..."
}

Refresh token

curl -X POST https://api.mail.land/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "rt_a1b2c3d4e5..."}'

La respuesta tiene la misma forma que la respuesta de inicio de sesión anterior (el AuthResponse completo), no solo estos tres campos:

Respuesta de actualización

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-09-25T14:00:00Z"
}

Cada token de actualización solo puede usarse una vez. La respuesta incluye un nuevo token de actualización para la siguiente rotación.

Cierre de sesión

Invalide la sesión actual:

POST https://api.mail.land/v1/auth/logout

Envíe { "refreshToken": "..." } en el cuerpo de la solicitud (o la cookie de refresh token). El refresh token se revoca; el access token sigue siendo válido hasta que expira: un encabezado Bearer por sí solo no revoca nada.

Logout

curl -X POST https://api.mail.land/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Revoque todas las sesiones activas:

POST https://api.mail.land/v1/auth/revoke-all-tokens

Revoke all sessions

curl -X POST https://api.mail.land/v1/auth/revoke-all-tokens \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Gestión de contraseñas

Olvidé mi contraseña

POST https://api.mail.land/v1/auth/forgot-password

Solicitud de contraseña olvidada

{
  "email": "[email protected]"
}

Forgot password

curl -X POST https://api.mail.land/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Envía un correo de restablecimiento de contraseña con un token de tiempo limitado.

Restablecer contraseña

POST https://api.mail.land/v1/auth/reset-password

confirmPassword es obligatorio y debe coincidir con newPassword; se aplican las mismas reglas de complejidad que en el registro.

Solicitud de restablecimiento de contraseña

{
  "token": "reset-token-from-email",
  "newPassword": "NewSecureP@ssw0rd!",
  "confirmPassword": "NewSecureP@ssw0rd!"
}

Reset password

curl -X POST https://api.mail.land/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "newPassword": "NewSecureP@ssw0rd!",
    "confirmPassword": "NewSecureP@ssw0rd!"
  }'

Validar token de restablecimiento

Verifique si un token de restablecimiento sigue siendo válido antes de mostrar el formulario de restablecimiento:

GET https://api.mail.land/v1/auth/validate-reset-token?token=reset-token-from-email

Validar token de restablecimiento

curl "https://api.mail.land/v1/auth/validate-reset-token?token=reset-token-from-email"

Respuesta de validación de token

{
  "valid": true,
  "message": "Token is valid"
}

Cambiar contraseña

Cambie la contraseña del usuario autenticado actualmente:

POST https://api.mail.land/v1/auth/change-password

Solicitud de cambio de contraseña

{
  "currentPassword": "OldP@ssw0rd!",
  "newPassword": "NewSecureP@ssw0rd!"
}

Change password

curl -X POST https://api.mail.land/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldP@ssw0rd!",
    "newPassword": "NewSecureP@ssw0rd!"
  }'

Gestión del perfil

Obtener usuario actual

GET https://api.mail.land/v1/auth/me

Get current user

curl https://api.mail.land/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Respuesta del usuario actual

{
  "id": "v4j2x7n1m9k5p3",
  "email": "[email protected]",
  "fullName": "John Doe",
  "companyName": "Acme",
  "avatarUrl": "https://cdn.mail.land/avatars/usr_a1b2c3d4e5.jpg",
  "status": "Active",
  "createdAt": "2026-01-15T08:00:00Z",
  "subscription": {
    "planName": "Pro",
    "monthlyEmailLimit": 50000,
    "rateLimitPerSecond": 10,
    "startDate": "2026-01-15T08:00:00Z",
    "endDate": "2026-10-15T08:00:00Z",
    "status": "Active"
  },
  "stats": {
    "credentialCount": 3,
    "domainCount": 2
  }
}

No hay campo firstName, lastName, phone, tenantId, role ni twoFactorEnabled en esta respuesta.

Actualizar perfil

PUT https://api.mail.land/v1/auth/profile

fullName es obligatorio; omitir companyName lo borra. Esta actualización coincide con la fila del usuario solo por su id de usuario, por lo que funciona desde cualquier espacio de trabajo en el que el usuario esté activo, no solo aquel en el que se creó la cuenta.

Solicitud de actualización de perfil

{
  "fullName": "Jane Smith",
  "companyName": "Acme"
}

Update profile

curl -X PUT https://api.mail.land/v1/auth/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jane Smith",
    "companyName": "Acme"
  }'

Subir avatar

POST https://api.mail.land/v1/account/avatar

Envíe una solicitud multipart/form-data con el archivo de imagen del avatar. Formatos compatibles: JPEG, PNG, GIF o WebP (se analiza el contenido del archivo, no solo la extensión). Tamaño máximo: 1 MB.

Upload avatar

curl -X POST https://api.mail.land/v1/account/avatar \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@/path/to/avatar.jpg"

MailLand admite inicio de sesión social a través de Google, GitHub y Microsoft:

Redirigir al proveedor

GET https://api.mail.land/auth/social/{provider}

Donde {provider} es google, github o microsoft. Esto redirige al usuario a la pantalla de consentimiento OAuth del proveedor.

Redirect to social provider

curl https://api.mail.land/auth/social/google

Gestionar la devolución de llamada

Después de que el usuario autoriza, el proveedor redirige de vuelta a MailLand con un código de autorización:

GET https://api.mail.land/auth/social/{provider}/callback?code=...

Social callback

curl "https://api.mail.land/auth/social/google/callback?code=authorization-code-from-provider"

La devolución de llamada (callback) es gestionada por MailLand, que redirige el navegador a {frontend}/{locale}/auth/callback?code=<código de un solo uso>&provider=.... Ese code es el código de un solo uso propio de MailLand, no el código de autorización del proveedor: páselo sin modificar al paso de intercambio siguiente.

Intercambiar por tokens

POST https://api.mail.land/v1/auth/social/exchange

Solicitud de intercambio social

{
  "code": "one-time-code-from-callback-redirect"
}

Exchange social code for tokens

curl -X POST https://api.mail.land/v1/auth/social/exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "one-time-code-from-callback-redirect"}'

Devuelve el mismo AuthResponse que el inicio de sesión regular.

Eliminar cuenta

La eliminación es por espacio de trabajo, no por cuenta de usuario, y solo un Owner del espacio de trabajo puede iniciarla. Programa la eliminación tras un periodo de gracia en lugar de eliminar de inmediato:

POST https://api.mail.land/v1/account/lifecycle/schedule-deletion

Solicitud de programación de eliminación

{
  "gracePeriodDays": 30
}

Programar eliminación

curl -X POST https://api.mail.land/v1/account/lifecycle/schedule-deletion \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"gracePeriodDays": 30}'

gracePeriodDays acepta de 7 a 90 (por defecto 30); los valores fuera de ese rango se ajustan al límite, no se rechazan. La eliminación programada se puede cancelar en cualquier momento antes de que termine el periodo de gracia:

POST https://api.mail.land/v1/account/lifecycle/cancel-deletion

Los Owners del espacio de trabajo programan la eliminación con POST /v1/account/lifecycle/schedule-deletion (gracePeriodDays de 7 a 90, por defecto 30, los valores fuera de rango se ajustan al límite) y pueden cancelarla con POST /v1/account/lifecycle/cancel-deletion hasta entonces. No existe el endpoint DELETE /v1/auth/delete-account, y esta acción no es por usuario: elimina todo el espacio de trabajo una vez transcurrido el periodo de gracia.

Respuestas de error

Estado	Código	Descripción
`400`	`VALIDATION_FAILED`	La solicitud de registro no superó la validación, con un array `errors[]`
`401`	`UNAUTHORIZED`	Correo electrónico o contraseña incorrectos
`403`	`FORBIDDEN`	La cuenta está inactiva
`409`	`CONFLICT`	El correo electrónico ya está registrado
`429`	`TOO_MANY_LOGIN_ATTEMPTS`	Demasiados intentos de inicio de sesión fallidos; la respuesta incluye `Retry-After`

Un correo no verificado no devuelve un error: el inicio de sesión responde 200 con requiresEmailVerification: true y un nuevo verificationTicket.

Próximos pasos

Autenticación de dos factores: agregar 2FA a su cuenta
Gestión de equipo: invitar miembros al equipo
Espacios de trabajo: gestionar múltiples espacios de trabajo
Claves API: crear claves API para el acceso servidor a servidor

Autenticación

Métodos de autenticaciónCopiar enlace de la sección

RegistroCopiar enlace de la sección

Verificación de correo electrónicoCopiar enlace de la sección

Inicio de sesiónCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Actualización de tokenCopiar enlace de la sección

Cierre de sesiónCopiar enlace de la sección

Gestión de contraseñasCopiar enlace de la sección

Olvidé mi contraseñaCopiar enlace de la sección

Restablecer contraseñaCopiar enlace de la sección

Validar token de restablecimientoCopiar enlace de la sección

Cambiar contraseñaCopiar enlace de la sección

Gestión del perfilCopiar enlace de la sección

Obtener usuario actualCopiar enlace de la sección

Actualizar perfilCopiar enlace de la sección

Subir avatarCopiar enlace de la sección

Autenticación socialCopiar enlace de la sección

Redirigir al proveedorCopiar enlace de la sección

Gestionar la devolución de llamadaCopiar enlace de la sección

Intercambiar por tokensCopiar enlace de la sección

Eliminar cuentaCopiar enlace de la sección

Respuestas de errorCopiar enlace de la sección

Próximos pasosCopiar enlace de la sección

En esta página

Métodos de autenticación

Registro

Verificación de correo electrónico

Inicio de sesión

Respuesta

Actualización de token

Cierre de sesión

Gestión de contraseñas

Olvidé mi contraseña

Restablecer contraseña

Validar token de restablecimiento

Cambiar contraseña

Gestión del perfil

Obtener usuario actual

Actualizar perfil

Subir avatar

Autenticación social

Redirigir al proveedor

Gestionar la devolución de llamada

Intercambiar por tokens

Eliminar cuenta

Respuestas de error

Próximos pasos