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. Copie-le tel quel dans ton projet, par exemple dans lib/agentmail.ts, puis importe-le :

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

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.
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. Les deux prennent { idempotencyKey } en second argument.

const { id } = await mail.emails.send(
  {
    from: "Factures <factures@envoi.atelier.ch>",
    to: "client@exemple.ch",
    subject: "Ta facture d'octobre",
    html: "<p>Merci pour ta commande.</p>",
  },
  { 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.

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.

await mail.contacts.update("lea@exemple.ch", {
  unsubscribed: false,
  properties: { ville: "Lausanne" },
})

Voir 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.

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.

Erreurs

Une erreur de l’API lève une AgentmailError, qui porte statusCode, name (le code décrit dans Erreurs), message et retryable.

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.

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é.