Documentation

Authentification

Échangez les identifiants de votre compte de service contre un token de courte durée, puis utilisez-le sur chaque appel API.

Identifiants

Créez un compte de service dans le portail pour obtenir une paire d'identifiants :

Identifiant	Format	Remarques
`api_key_id`	`mvk_id_...`	Identifie le compte de service. Peut être stocké avec votre configuration
`api_key_secret`	`mvk_sec_...`	Affiché une seule fois, à la création. Stockez-le dans un gestionnaire de secrets et ne le committez jamais

Si vous perdez le secret, il est irrécupérable, mais vous pouvez régénérer la paire depuis le portail. La régénération invalide immédiatement l'ancien secret.

Obtenir un token

Échangez les identifiants contre un JWT. Les tokens sont valides 1 heure.

curl -X POST https://api.mailverick.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": "mvk_id_xxxxxxxxxx",
    "api_key_secret": "mvk_sec_xxxxxxxxxx"
  }'

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Champ	Type	Description
`access_token`	string	Le bearer token à envoyer sur les requêtes suivantes
`expires_in`	number	Durée de vie en secondes
`token_type`	string	Toujours `Bearer`

Utiliser le token

Passez-le dans l'en-tête Authorization sur chaque appel à un endpoint protégé.

curl -X POST https://api.mailverick.com/v1/send-email \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Échangez un nouveau token avant l'expiration de l'ancien. N'en demandez pas un par appel API : l'échange est volontairement plus lent qu'une requête normale, et un token est réutilisable pendant toute son heure. Notre SDK Node.js gère l'échange et le renouvellement pour vous.

Permissions

Chaque compte de service porte son propre jeu de permissions, ce qui permet de limiter une clé à ce dont elle a besoin. Une clé intégrée dans un formulaire d'inscription ne devrait pas pouvoir envoyer d'emails.

Permission	Donne accès à
`email:send`	Envoyer un email, et la soumission SMTP
`email:validate`	Validation d'adresses

Un appel vers un endpoint pour lequel la clé n'est pas autorisée renvoie 403, quelles que soient les autres permissions du token. Vous pouvez créer jusqu'à 3 comptes de service par organisation.

Erreurs

Statut	Quand
`400`	Identifiants manquants ou mal formés dans la requête d'échange
`401`	Key ID inconnu ou secret incorrect
`401`	Sur un endpoint protégé : token manquant, mal formé ou expiré
`403`	Token valide, mais le compte de service n'a pas la permission pour cet endpoint
`503`	Nous n'avons pas pu vérifier les identifiants pour le moment. La clé est valide : réessayez au lieu de la renouveler

SMTP

La soumission SMTP n'utilise pas de token. Authentifiez-vous directement avec les mêmes identifiants, le key ID comme nom d'utilisateur et le secret comme mot de passe. Voir Envoyer un email pour l'hôte et les ports.

Et ensuite

Avec un token en main, vous pouvez envoyer un email ou valider une adresse.