Configuration
Trois façons de construire un client, toutes les options, et ce qu'il refuse avant qu'une requête ne parte.
Options
import OpenEmail, { createOpenEmail, init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY })await openemail.me.ping() export const billing = createOpenEmail({ apiKey: process.env.BILLING_API_KEY! }) const pinned = new OpenEmail({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk' }) const quick = new OpenEmail('oe_live_…')| Point d'entrée | Ce que vous obtenez |
|---|---|
| `init(options)` | Configure le client partagé et le renvoie. openemail est ce client à partir de là, dans chaque module, et tout ce que vous omettez est lu depuis l'environnement. |
| `openemail` | Le client partagé. Utilisé avant init, il se construit lui-même à partir de OPENEMAIL_API_KEY et OPENEMAIL_BASE_URL au premier appel. |
| `createOpenEmail(options)` | Un client distinct avec le même repli sur l'environnement, pour une deuxième clé à côté de la clé partagée, ou pour construire l'instance qu'exporte votre propre module. createClient est la même fonction sous le nom qu'utilise le SDK envless. |
| `new OpenEmail(options)` ou `new OpenEmail(apiKey)` | Un client distinct construit exactement avec ce que vous passez. Il ne lit aucun environnement : apiKey est donc obligatoire. C'est aussi l'export par défaut. |
init({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk', timeoutMs: 30_000, maxRetries: 2, fetch: myFetch, headers: {}, userAgent: 'billing-service/1.4', disableUpdateNotice: true,})| Option | Par défaut | Remarques |
|---|---|---|
| `apiKey` | OPENEMAIL_API_KEY | Lu depuis l'environnement par init et createOpenEmail. Doit commencer par oe_live_ ou oe_test_. |
| `baseUrl` | https://api.openemail.uk | Ou OPENEMAIL_BASE_URL. Une barre oblique finale est retirée, et init et createOpenEmail placent https:// devant un hôte nu, ou http:// devant localhost. |
| `timeoutMs` | 30000 | Par tentative, pas par appel. Couvre la lecture du corps, pas seulement celle des en-têtes. 0 le désactive. |
| `maxRetries` | 2 | Tentatives supplémentaires après la première, sur les appels qu'il est sûr de répéter. Se règle sur le client, pas par appel. |
| `fetch` | le global | Lié pour vous. Passez-en un pour un proxy, un binding de Worker ou un double de test. |
| `headers` | {} | Envoyés à chaque requête. |
| `userAgent` | openemail-sdk/<version> | Envoyé depuis tous les runtimes sauf un navigateur, qui n'autorise pas à le définir. |
| `disableUpdateNotice` | false | Ignore la vérification, une fois par processus, d'une version plus récente sur npm. La vérification ne s'exécute que lorsque la sortie va vers un terminal, et OPENEMAIL_DISABLE_UPDATE_NOTICE la désactive aussi. |
| `dangerouslyAllowBrowser` | false | Laisse le client démarrer là où window et document existent. Prévu pour un harnais de test qui les définit, pas pour une page. |
Ce qu'il refuse avant d'envoyer
Ceux-ci lèvent une simple Error depuis la ligne qui portait la mauvaise valeur, au lieu de ressortir en échec déroutant à votre premier envoi. Le message dit ce qui n'allait pas et quoi passer à la place.
| Refusé | Pourquoi |
|---|---|
| Aucune clé | Ni apiKey ni OPENEMAIL_API_KEY n'était défini : il n'y a donc rien pour s'authentifier. |
| Un cookie ou un jeton de session | Seuls oe_live_ et oe_test_ authentifient ici, et l'API le dit aussi. La vérification porte sur le préfixe et rien de plus : une clé révoquée échoue donc quand même sur le réseau. |
| Un `baseUrl` qui n'est pas une URL http ou https | Rien d'autre ne peut être récupéré, et une valeur non validée échouerait plus tard en TypeError brute venue de tout autre part. |
| Un navigateur | La clé serait lisible par quiconque ouvre les devtools. Voir la section ci-dessous. |
| Aucun `fetch` nulle part | Passez-en un via fetch, ou exécutez sur Node 20+. |
| Un id vide ou fait uniquement de points sur n'importe quelle méthode | Levé à l'appel de la méthode. Un segment de chemin fait de points est supprimé par tous les analyseurs d'URL : la requête atteindrait donc un autre endpoint. |
Il n'y a pas d'option testMode et il n'y en aura pas. Le schéma de la clé fait partie de l'identifiant plutôt que d'être un indice : le mode est donc une propriété de la clé. openemail.mode lit le préfixe et ne décide rien.
Un client, plusieurs clés
Construisez le client une fois et partagez-le. Une nouvelle instance par requête jette pour rien le binding de fetch et la configuration, et aucun état qu'il porte n'est propre à un appelant.
Pour le cas qui imposerait sinon une instance par clé, comme un job qui envoie pour le compte de plusieurs espaces de travail, passez apiKey sur l'appel. Il remplace l'en-tête Authorization pour cette requête et ne laisse rien derrière lui sur le client.
await openemail.emails.send(message) await openemail.emails.send(message, { apiKey: workspace.apiKey }) await openemail.threads.list({ folder: 'inbox', apiKey: workspace.apiKey })await openemail.webhooks.list({ apiKey: workspace.apiKey })Toutes les méthodes hors tempMail l'acceptent dans leur dernier argument, à côté de signal, et sur une liste c'est le même objet que les filtres. Elle est vérifiée avant l'envoi de la requête, par la règle qu'utilise le constructeur : une faute de frappe lève donc une Error nommant { apiKey } on this call plutôt qu'un 401 portant sur un identifiant qu'il faut ensuite aller chercher. Un appel retenté conserve la clé qu'on lui a donnée.
signal est un AbortSignal. L'interrompre arrête la requête, ainsi que toute nouvelle tentative en attente derrière elle.
openemail.mode décrit la clé avec laquelle le client a été CONSTRUIT et ne suit pas une surcharge. Dès qu'un client sert plusieurs clés, il n'y a plus de mode unique à rapporter : lisez-le sur la clé que vous avez passée.
Depuis un navigateur
Le client refuse de démarrer dans un navigateur et lève avant qu'une requête ne parte. Une clé dans une page est une clé que vous avez publiée : elle peut envoyer du courrier et lire la messagerie pour quiconque ouvre les devtools. Appelez-le plutôt depuis un serveur, une fonction serverless ou un script.
Les boîtes jetables font exception. createTempMail() construit un client qui ne porte aucune clé API : il est donc sûr dans une page. Il crée des boîtes anonymement, et chaque lecture envoie le jeton renvoyé par create, soit par appel via inboxToken, soit une fois via createTempMail({ inboxToken }).
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })Si vous passez quand même dangerouslyAllowBrowser: true, l'API laisse passer exactement Content-Type, Authorization et Idempotency-Key par son preflight CORS : un en-tête supplémentaire dans headers fait donc échouer le preflight plutôt que la requête, et ce qu'un navigateur en rapporte n'apprend rien d'utile.