Authentification

Chaque requête adressée à l’API Emailit doit comporter un identifiant dans l’en-tête Authorization. Cette page présente les deux types d’identifiants (clés API et jetons d’accès OAuth), ce que permet chaque portée et toutes les erreurs d’authentification que vous pouvez recevoir.

Clés API

Une clé API appartient à un espace de travail, et chaque requête effectuée avec elle agit sur cet espace de travail. Les clés se présentent ainsi :

secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG

Soit secret_ suivi de 32 lettres et chiffres. Les clés créées avant le format secret_ n’ont pas de préfixe et continuent de fonctionner.

Créez des clés dans le tableau de bord, sous Email API›API Keys, ou avec Créer une clé API. Le secret n’est affiché qu’une seule fois, lorsque vous créez ou régénérez la clé : enregistrez-le immédiatement. Pour les gérer, consultez Clés API.

Les mêmes clés servent de mot de passe SMTP pour le relais SMTP.

Envoyer la clé avec chaque requête

Utilisez le schéma Bearer dans l’en-tête Authorization. L’API n’accepte pas de clé dans la chaîne de requête ni dans le corps de la requête.

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();

import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()

Les SDK définissent cet en-tête pour vous lorsque vous transmettez la clé au client.

Portées

Chaque clé possède l’une des deux portées. Vous la choisissez à la création de la clé et ne pouvez plus la modifier ensuite.

Une clé sending peut appeler ces endpoints, et aucun autre :

La lecture des e-mails (liste, récupération, MIME brut, corps, métadonnées, pièces jointes et statut) nécessite une clé full. Lorsqu’une clé sending appelle un autre endpoint, l’API renvoie 403 avec Permission denied: full (ou Permission denied: read pour les endpoints de lecture des e-mails).

La page Tous les endpoints indique la portée de chaque endpoint.

Restreindre une clé à un domaine

Une clé sending peut aussi être limitée à un seul domaine d’envoi. Transmettez l’ID du domaine dans sending_domain_id lorsque vous créez la clé. Une clé restreinte ne peut envoyer que depuis des adresses de ce domaine. Tout autre domaine dans from renvoie 403 :

{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}

Les restrictions de domaine ne s’appliquent qu’aux clés sending. Une clé full a toujours accès à tous les domaines de l’espace de travail.

Jetons d’accès OAuth

Les applications qui agissent pour le compte d’un utilisateur Emailit, comme les clients MCP et les intégrations tierces, ne demandent pas de clé API. Elles utilisent OAuth 2.1 : l’utilisateur se connecte à Emailit, choisit les espaces de travail que l’application peut utiliser (tous ou seulement certains) et approuve la portée sending ou full, puis l’application reçoit un jeton d’accès. L’utilisateur peut modifier ou révoquer cet accès depuis Applications connectées.

Envoyez les jetons d’accès dans le même en-tête que les clés API :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Un jeton d’accès est valable 15 minutes et agit sur l’espace de travail par défaut de l’autorisation, avec la portée accordée et le rôle de l’utilisateur dans cet espace de travail. Les applications le renouvellent avec le jeton d’actualisation. Pour créer une application OAuth, consultez Applications OAuth.

Erreurs d’authentification

L’authentification a lieu avant tout le reste : ces erreurs peuvent donc provenir de n’importe quel endpoint.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}

{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}

Espaces de travail non vérifiés

Les nouveaux espaces de travail démarrent non vérifiés. Tant qu’Emailit n’a pas approuvé l’accès production, l’API n’envoie qu’aux adresses e-mail de compte des membres de l’espace de travail. Un envoi, une relance ou un transfert vers toute autre personne renvoie 403 avec le code unverified_workspace_recipient et la liste blocked_recipients, et aucune campagne ne peut être envoyée. Vos clés API fonctionnent normalement pour tout le reste.

Garder vos clés secrètes

Une clé API donne accès à votre espace de travail : traitez-la comme un mot de passe.

• Appelez l’API uniquement depuis votre serveur. Ne placez jamais une clé dans du JavaScript exécuté dans le navigateur, dans une application mobile ni dans tout autre code qui s’exécute sur l’appareil de quelqu’un d’autre.
• Ne mettez pas les clés sous contrôle de version. Chargez-les depuis des variables d’environnement ou un gestionnaire de secrets.
• Créez une clé par application et par environnement, et nommez-la d’après l’endroit où elle est utilisée : vous pourrez en révoquer une sans casser les autres.
• Donnez à chaque clé l’accès minimal dont elle a besoin : une clé sending limitée à un domaine suffit à la plupart des applications.
• Vérifiez last_used_at avec Lister les clés API et supprimez les clés que vous n’utilisez plus.
• Si une clé fuite, régénérez-la ou supprimez-la sans attendre. L’ancien secret cesse immédiatement de fonctionner.

Voir aussi