Vanilla JavaScript

Use the Mailpulse SDK with vanilla JavaScript or TypeScript.

Installation


npm install mailpulse

Creating a Client


import { MailpulseClient } from 'mailpulse';
 
const client = new MailpulseClient({
  apiKey: 'your-api-key',
  apiUrl: 'https://mailpulse-io.lyten.agency', // optional, this is the default
});

You can also use the factory function:


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

Get Global Stats

Retrieve organization-wide tracking statistics.


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

Response Type


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

List Campaigns

Get all campaigns for your organization.


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

Response Type


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

Get Campaign Details

Get a specific campaign with its emails and aggregated stats.


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

Response Type


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;
}

Get Campaign Stats

Get detailed analytics for a campaign with time-series data.


const stats = await client.getCampaignStats('campaign-id', {
  period: '30d', // '7d', '30d', '90d', or 'YYYY-MM-DD,YYYY-MM-DD'
});
 
console.log(stats.stats.openRate);
console.log(stats.openAndClicks); // Daily breakdown
console.log(stats.topLinks); // Most clicked links

Period Options

Value	Description
`7d`	Last 7 days
`30d`	Last 30 days (default)
`90d`	Last 90 days
`YYYY-MM-DD,YYYY-MM-DD`	Custom date range

Response Type


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;
}

Register Email for Tracking


const result = await client.registerEmail({
  recipient: 'user@example.com',
  subject: 'Welcome to our newsletter',
  htmlContent: '<html>...</html>',
  campaignId: 'optional-campaign-id',
  metadata: { userId: '123' }, // optional
});
 
console.log(result.emailTrackingId);
console.log(result.pixelUrl); // Add to email for open tracking
console.log(result.links); // Tracked links to replace in email

Request Type


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

Response Type


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

Error Handling

The SDK throws MailpulseApiError for API errors.


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

TypeScript Support

All types are exported from the main package:


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