Authentification

MailLand prend en charge deux méthodes d'authentification : les tokens Bearer (JWT) pour les sessions utilisateur et les clés API pour l'intégration serveur à serveur. Toutes les requêtes API nécessitent une authentification via l'en-tête Authorization.

Méthodes d'authentificationCopier le lien de la section

InscriptionCopier le lien de la section

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

{
  "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"
  }'

Les champs inconnus (comme un tenantName envoyé par erreur) sont ignorés silencieusement.

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

Le statut de la réponse est 201.

Après l'inscription, vérifiez l'adresse e-mail avant de vous connecter.

Vérification de l'e-mailCopier le lien de la section

L'inscription envoie un code à 6 chiffres par e-mail. Appelez POST /v1/auth/verify-email-ticket avec { "ticket": "<verificationTicket>", "code": "123456" } ; en cas de succès, la réponse contient les tokens de connexion.

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

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

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

Renvoyer l'e-mail de vérification : appelez POST /v1/auth/resend-verification-ticket avec { "ticket": "..." }. La requête est limitée en fréquence et renvoie un nouveau ticket.

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

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

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

ConnexionCopier le lien de la section

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

{
  "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!"
  }'

RéponseCopier le lien de la section

La réponse de connexion varie en fonction de l'état du compte :

Connexion réussie :

{
  "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
}

Il n'y a pas d'objet user ni de champ role dans la réponse. Un compte non vérifié reçoit un 200 avec requiresEmailVerification: true et un verificationTicket, pas une erreur.

Authentification à deux facteurs requise :

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

Lorsque requiresTwoFactor est true, complétez la vérification 2FA avant de recevoir les tokens.

Actualisation du tokenCopier le lien de la section

Les tokens d'accès expirent après 60 minutes. Utilisez le token d'actualisation pour obtenir un nouveau token d'accès :

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

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

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

La réponse a la même forme que la réponse de connexion ci-dessus (l'AuthResponse complet), pas seulement ces trois champs :

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

DéconnexionCopier le lien de la section

Invalider la session en cours :

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

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

Révoquer toutes les sessions actives :

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

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

Gestion des mots de passeCopier le lien de la section

Mot de passe oubliéCopier le lien de la section

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

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

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

Envoie un e-mail de réinitialisation du mot de passe avec un token à durée limitée.

Réinitialisation du mot de passeCopier le lien de la section

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

confirmPassword est requis et doit correspondre à newPassword ; les mêmes règles de complexité qu'à l'inscription s'appliquent.

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

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!"
  }'

Validation du token de réinitialisationCopier le lien de la section

Vérifiez si un token de réinitialisation est encore valide avant d'afficher le formulaire de réinitialisation :

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

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

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

Changement de mot de passeCopier le lien de la section

Changer le mot de passe de l'utilisateur actuellement authentifié :

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

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

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!"
  }'

Gestion du profilCopier le lien de la section

Obtenir l'utilisateur actuelCopier le lien de la section

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

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

{
  "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
  }
}

Il n'y a pas de champ firstName, lastName, phone, tenantId, role ni twoFactorEnabled dans cette réponse.

Mettre à jour le profilCopier le lien de la section

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

fullName est obligatoire ; omettre companyName l'efface. Cette mise à jour ne fait correspondre que l'identifiant de l'utilisateur, elle fonctionne donc depuis n'importe quel espace de travail où l'utilisateur est actif, pas seulement celui où le compte a été créé.

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

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"
  }'

Télécharger un avatarCopier le lien de la section

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

Envoyez une requête multipart/form-data avec le fichier image de l'avatar. Formats pris en charge : JPEG, PNG, GIF ou WebP (le contenu est vérifié, pas seulement l'extension). Taille maximale : 1 Mo.

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

Authentification socialeCopier le lien de la section

MailLand prend en charge la connexion sociale via Google, GitHub et Microsoft :

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

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

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

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

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

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

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

Suppression du compteCopier le lien de la section

La suppression se fait par espace de travail, pas par compte utilisateur, et seul un Owner de l'espace de travail peut la déclencher. Elle planifie la suppression après un délai de grâce plutôt que de supprimer immédiatement :

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

{
  "gracePeriodDays": 30
}

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 accepte de 7 à 90 (par défaut 30) ; les valeurs hors de cette plage sont plafonnées, pas refusées. La suppression planifiée peut être annulée à tout moment avant la fin du délai de grâce :

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

Réponses d'erreurCopier le lien de la section

Un e-mail non vérifié ne renvoie pas d'erreur : la connexion répond 200 avec requiresEmailVerification: true et un nouveau verificationTicket.

Prochaines étapesCopier le lien de la section

• Authentification à deux facteurs : ajouter la 2FA à votre compte
• Gestion d'équipe : inviter des membres de l'équipe
• Espaces de travail : gérer plusieurs espaces de travail
• Clés API : créer des clés API pour l'accès serveur à serveur