# SDK TypeScript Le SDK est un fichier TypeScript unique, sans dépendance. Il fonctionne avec Node 18 et plus, Bun, Deno et les environnements edge. Il est fait pour le serveur : la clé d’API y donne le droit d’envoyer au nom de ton espace, elle ne doit jamais arriver dans un navigateur. ## Où le trouver Le fichier est publié à l’adresse [mail.hgdc.ch/sdk/agentmail.ts](https://mail.hgdc.ch/sdk/agentmail.ts). Copie-le tel quel dans ton projet, par exemple dans `lib/agentmail.ts`, puis importe-le : ```ts import { Agentmail } from "./lib/agentmail" const mail = new Agentmail() ``` Il n’y a ni paquet à installer ni version à suivre. Pour le mettre à jour, recopie le fichier. ## Constructeur ```ts new Agentmail(options?) ``` | Option | Type | Défaut | Description | | ------------------------- | -------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | string | `AGENTMAIL_API_KEY` | Clé `am_…` de ton espace. | | `baseUrl` | string | `AGENTMAIL_BASE_URL`, puis l’adresse de production du fichier | Racine de l’API. Voir [Introduction à l’API](/docs/reference/api/). | | `fetch` | fonction | `fetch` global | Implémentation de `fetch` à utiliser : tests, proxy. | | `maxRetries` | nombre | `2` | Nombre de nouveaux essais après le premier, voir Réessais automatiques plus bas. | | `sleep` | fonction | attente réelle | Attente entre deux essais, à remplacer dans les tests. | | `dangerouslyAllowBrowser` | boolean | `false` | Autorise le SDK dans un navigateur. À éviter : la clé y serait lisible par n’importe qui. Sans cette option, le constructeur lève une erreur dans un navigateur. | Sans `apiKey`, le SDK lit `AGENTMAIL_API_KEY`. Une clé absente donne une `AgentmailError` avec `name: "missing_api_key"` au premier appel. ## Méthodes Toutes les méthodes renvoient une promesse. Les types exacts sont exportés par le fichier. ### E-mails - `mail.emails.send(input, options?)` : envoie un e-mail, renvoie `{ id }`. - `mail.emails.batch(inputs, options?)` : envoie de 1 à 100 e-mails, renvoie `{ data: [{ id }] }`. - `mail.emails.get(id)` : lit le statut d’un e-mail. `emails.send` accepte `template: { id, variables }` à la place de `html` ou `text`. `emails.batch` est tout ou rien : un élément refusé n’envoie aucun e-mail du lot. Voir [API e-mails](/docs/reference/api-emails/#post-emailsbatch). Les deux prennent `{ idempotencyKey }` en second argument. ```ts const { id } = await mail.emails.send( { from: "Factures ", to: "client@exemple.ch", subject: "Ta facture d'octobre", html: "

Merci pour ta commande.

", }, { idempotencyKey: "facture-118" }, ) ``` ### Événements - `mail.events.send({ name, email, first_name?, last_name?, properties? })` : fait entrer un contact dans les workflows qui attendent cet événement. Voir [Déclencher un workflow](/docs/guides/declencher-un-workflow/). ### Contacts - `mail.contacts.create(input)` : ajoute ou met à jour un contact. - `mail.contacts.get(idOrEmail)` : lit un contact. - `mail.contacts.list(query?)` : lit une page, avec `has_more` et `next_cursor`. - `mail.contacts.listAll({ limit? })` : enchaîne les pages, en ne chargeant qu’une page à la fois. - `mail.contacts.update(idOrEmail, input)` : modifie un contact. - `mail.contacts.remove(idOrEmail)` : supprime un contact. ```ts await mail.contacts.update("lea@exemple.ch", { unsubscribed: false, properties: { ville: "Lausanne" }, }) ``` Voir [API contacts](/docs/reference/api-contacts/). ### Listes - `mail.lists.list()` : toutes les listes de l’espace. - `mail.lists.create({ name })` : crée une liste. ### Campagnes - `mail.broadcasts.create(input)` : crée une campagne. Avec `send: true`, elle part tout de suite. - `mail.broadcasts.get(id)` : lit une campagne. - `mail.broadcasts.list()` : les 100 campagnes les plus récentes. - `mail.broadcasts.send(id)` : lance une campagne en brouillon. Voir [API campagnes](/docs/reference/api-campagnes/). ### Modèles - `mail.templates.list()` : les modèles de l’espace, sans leur contenu. - `mail.templates.get(id)` : un modèle, avec son HTML et son texte. Voir [API modèles](/docs/reference/api-modeles/). ## Erreurs Une erreur de l’API lève une `AgentmailError`, qui porte `statusCode`, `name` (le code décrit dans [Erreurs](/docs/reference/erreurs/)), `message` et `retryable`. ```ts import { Agentmail, AgentmailError } from "./lib/agentmail" try { await mail.emails.send({ /* … */ }) } catch (error) { if (error instanceof AgentmailError && error.retryable) { // Réessayer plus tard a des chances d'aboutir. } throw error } ``` `retryable` vaut `true` sur `429` (sauf quota du jour), `500` et erreur réseau. ## Réessais automatiques Le SDK réessaie seul sur `429` (sauf `daily_quota_exceeded`), `500` et erreur réseau. Il attend 0,5 s, puis 1 s, et respecte l’en-tête `Retry-After` quand il est présent. Au-delà de `maxRetries`, l’erreur remonte. Un envoi n’est réessayé automatiquement que s’il porte une clé d’idempotence. Sans elle, un nouvel essai pourrait doubler le message. Voir [Envoyer sans doublon](/docs/guides/envoyer-sans-doublon/). ## Si ça ne marche pas - **`AgentmailError: missing_api_key`** : `AGENTMAIL_API_KEY` n’est pas défini dans l’environnement du processus. Charge `.env` avant le premier appel. - **Le SDK refuse de démarrer dans une page web** : c’est voulu. Déplace l’appel dans une route serveur. - **Les tests réessaient trop lentement** : passe une fonction `sleep` qui ne fait rien, et un `fetch` simulé.