Vanilla JavaScript

Utilisez le SDK Mailpulse avec vanilla JavaScript ou TypeScript.

Installation


npm install mailpulse

Créer un Client


import { MailpulseClient } from 'mailpulse';
 
const client = new MailpulseClient({
  apiKey: 'votre-cle-api',
  apiUrl: 'https://mailpulse-io.lyten.agency', // optionnel, c'est la valeur par défaut
});

Vous pouvez aussi utiliser la fonction factory :


import { createMailpulseClient } from 'mailpulse';
 
const client = createMailpulseClient({
  apiKey: 'votre-cle-api',
});

Obtenir les Statistiques Globales

Récupérer les statistiques de suivi à l’échelle de l’organisation.


const stats = await client.getStats();
 
console.log(stats);
// {
//   totalEmails: 1250,
//   totalOpens: 890,
//   totalClicks: 234,
//   openRate: 71.2,
//   clickRate: 18.72
// }

Type de Réponse


interface TrackingStats {
  totalEmails: number;
  totalOpens: number;
  totalClicks: number;
  openRate: number;
  clickRate: number;
}

Lister les Campagnes

Obtenir toutes les campagnes de votre organisation.


const { campaigns } = await client.getCampaigns();
 
campaigns.forEach(campaign => {
  console.log(`${campaign.name} - ${campaign.id}`);
});

Type de Réponse


interface Campaign {
  id: string;
  name: string;
  createdAt: string;
}
 
interface CampaignsResponse {
  campaigns: Campaign[];
}

Obtenir les Détails d’une Campagne

Obtenir une campagne spécifique avec ses emails et statistiques agrégées.


const campaign = await client.getCampaign('campaign-id');
 
console.log(campaign.name);
console.log(campaign.stats.openRate);
console.log(campaign.emails.length);

Type de Réponse


interface CampaignDetails {
  id: string;
  name: string;
  createdAt: string;
  stats: TrackingStats;
  links: LinkStats[];
  emails: EmailSummary[];
}
 
interface EmailSummary {
  id: string;
  trackingId: string;
  recipient: string;
  subject: string;
  createdAt: string;
  opens: number;
  clicks: number;
}

Obtenir les Statistiques de Campagne

Obtenir des analyses détaillées pour une campagne avec des données chronologiques.


const stats = await client.getCampaignStats('campaign-id', {
  period: '30d', // '7d', '30d', '90d', ou 'YYYY-MM-DD,YYYY-MM-DD'
});
 
console.log(stats.stats.openRate);
console.log(stats.openAndClicks); // Répartition journalière
console.log(stats.topLinks); // Liens les plus cliqués

Options de Période

Valeur	Description
`7d`	7 derniers jours
`30d`	30 derniers jours (défaut)
`90d`	90 derniers jours
`YYYY-MM-DD,YYYY-MM-DD`	Plage de dates personnalisée

Type de Réponse


interface CampaignStatsResponse {
  campaign: Campaign;
  period: {
    start: string;
    end: string;
  };
  stats: {
    totalEmails: number;
    totalOpens: number;
    totalClicks: number;
    openRate: number;
    clickThroughRate: number;
    uniqueRecipients: number;
    noInteraction: number;
  };
  openAndClicks: DailyStats[];
  topLinks: LinkStats[];
}
 
interface DailyStats {
  date: string;
  opens: number;
  clicks: number;
  emails: number;
}

Enregistrer un Email pour le Suivi

Enregistrer un email pour obtenir des URLs de suivi.


const result = await client.registerEmail({
  recipient: 'user@example.com',
  subject: 'Bienvenue à notre newsletter',
  htmlContent: '<html>...</html>',
  campaignId: 'optional-campaign-id',
  metadata: { userId: '123' }, // optionnel
});
 
console.log(result.emailTrackingId);
console.log(result.pixelUrl); // Ajouter à l'email pour le suivi d'ouverture
console.log(result.links); // Liens suivis à remplacer dans l'email

Type de Requête


interface RegisterEmailRequest {
  recipient: string;
  subject: string;
  htmlContent: string;
  campaignId?: string;
  metadata?: Record<string, unknown>;
}

Type de Réponse


interface RegisterEmailResponse {
  emailTrackingId: string;
  links: TrackedLink[];
  pixelUrl: string;
}
 
interface TrackedLink {
  originalUrl: string;
  trackingId: string;
  trackingUrl: string;
}

Envoyer un Email

Envoyer un email directement via Mailpulse avec suivi automatique. Nécessite un domaine d’envoi vérifié.


const result = await client.sendEmail({
  from: 'Newsletter <news@votredomaine.com>',
  to: 'user@example.com',
  subject: 'Bienvenue dans notre newsletter',
  htmlContent: '<html><body><a href="https://example.com">Cliquez ici</a></body></html>',
  campaignId: 'serie-bienvenue', // optionnel
  replyTo: 'reply@votredomaine.com', // optionnel
  metadata: { userId: '123' }, // optionnel
});
 
console.log(result.id); // ID email Resend
console.log(result.emailTrackingId); // ID de suivi Mailpulse
console.log(result.links); // Liens suivis

Type de Requête


interface SendEmailRequest {
  from: string;
  to: string | string[];
  subject: string;
  htmlContent: string;
  replyTo?: string;
  cc?: string | string[];
  bcc?: string | string[];
  campaignId?: string;
  metadata?: Record<string, unknown>;
}

Type de Réponse


interface SendEmailResponse {
  id: string;
  emailTrackingId: string;
  from: string;
  to: string[];
  subject: string;
  links: TrackedLink[];
  pixelUrl: string;
}

Gestion des Erreurs

Le SDK lève MailpulseApiError pour les erreurs d’API.


import { MailpulseApiError } from 'mailpulse';
 
try {
  const stats = await client.getCampaignStats('invalid-id');
} catch (error) {
  if (error instanceof MailpulseApiError) {
    console.error(`Erreur API : ${error.message} (${error.status})`);
  }
}

Support TypeScript

Tous les types sont exportés depuis le paquet principal :


import type {
  MailpulseConfig,
  TrackingStats,
  Campaign,
  CampaignDetails,
  CampaignStatsResponse,
  RegisterEmailRequest,
  RegisterEmailResponse,
  SendEmailRequest,
  SendEmailResponse,
} from 'mailpulse';