React

Use the Mailpulse SDK with React using the built-in Provider and hooks.

Installation


npm install mailpulse react

Setup Provider

Wrap your application with the MailpulseProvider:


import { MailpulseProvider } from 'mailpulse/react';
 
function App() {
  return (
    <MailpulseProvider apiKey="your-api-key">
      <YourApp />
    </MailpulseProvider>
  );
}

Provider Props

Prop	Type	Required	Description
`apiKey`	`string`	Yes	Your Mailpulse API key
`apiUrl`	`string`	No	Custom API URL
`children`	`ReactNode`	Yes	Child components

useStats

Fetch global tracking statistics.


import { useStats } from 'mailpulse/react';
 
function StatsCard() {
  const { data, isLoading, error, refetch } = useStats();
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div>
      <p>Total Emails: {data.totalEmails}</p>
      <p>Open Rate: {data.openRate}%</p>
      <p>Click Rate: {data.clickRate}%</p>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Return Type


interface UseStatsResult {
  data: TrackingStats | null;
  isLoading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

useCampaigns

Fetch all campaigns.


import { useCampaigns } from 'mailpulse/react';
 
function CampaignList() {
  const { data, isLoading, error } = useCampaigns();
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <ul>
      {data.campaigns.map(campaign => (
        <li key={campaign.id}>{campaign.name}</li>
      ))}
    </ul>
  );
}

Return Type


interface UseCampaignsResult {
  data: CampaignsResponse | null;
  isLoading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

useCampaign

Fetch a specific campaign with details.


import { useCampaign } from 'mailpulse/react';
 
function CampaignDetails({ campaignId }: { campaignId: string }) {
  const { data, isLoading, error } = useCampaign(campaignId);
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div>
      <h1>{data.name}</h1>
      <p>Emails: {data.stats.totalEmails}</p>
      <p>Open Rate: {data.stats.openRate}%</p>
 
      <h2>Emails</h2>
      <ul>
        {data.emails.map(email => (
          <li key={email.id}>
            {email.subject} - {email.opens} opens
          </li>
        ))}
      </ul>
    </div>
  );
}

Parameters

Parameter	Type	Description
`campaignId`	`string`	Campaign ID to fetch

useCampaignStats

Fetch detailed campaign analytics with time-series data.


import { useCampaignStats } from 'mailpulse/react';
 
function CampaignAnalytics({ campaignId }: { campaignId: string }) {
  const { data, isLoading, error } = useCampaignStats(campaignId, {
    period: '30d',
  });
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div>
      <h1>{data.campaign.name}</h1>
      <p>Period: {data.period.start} - {data.period.end}</p>
 
      <h2>Stats</h2>
      <p>Open Rate: {data.stats.openRate}%</p>
      <p>Click Through Rate: {data.stats.clickThroughRate}%</p>
 
      <h2>Daily Breakdown</h2>
      {data.openAndClicks.map(day => (
        <div key={day.date}>
          {day.date}: {day.opens} opens, {day.clicks} clicks
        </div>
      ))}
 
      <h2>Top Links</h2>
      {data.topLinks.map(link => (
        <div key={link.url}>
          {link.url}: {link.clicks} clicks
        </div>
      ))}
    </div>
  );
}

Parameters

Parameter	Type	Description
`campaignId`	`string`	Campaign ID
`options.period`	`string`	Period filter (`7d`, `30d`, `90d`, or date range)

useRegisterEmail


import { useRegisterEmail } from 'mailpulse/react';
 
function EmailForm() {
  const { registerEmail, isLoading, error, data } = useRegisterEmail();
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
 
    const result = await registerEmail({
      recipient: 'user@example.com',
      subject: 'Welcome!',
      htmlContent: '<html>...</html>',
      campaignId: 'my-campaign',
    });
 
    if (result) {
      console.log('Tracking ID:', result.emailTrackingId);
      console.log('Pixel URL:', result.pixelUrl);
    }
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Registering...' : 'Register Email'}
      </button>
      {error && <p>Error: {error.message}</p>}
      {data && <p>Registered! ID: {data.emailTrackingId}</p>}
    </form>
  );
}

Return Type


interface UseRegisterEmailResult {
  registerEmail: (data: RegisterEmailRequest) => Promise<RegisterEmailResponse | null>;
  isLoading: boolean;
  error: Error | null;
  data: RegisterEmailResponse | null;
}

useMailpulseClient

Access the underlying client directly for advanced use cases.


import { useMailpulseClient } from 'mailpulse/react';
 
function CustomComponent() {
  const client = useMailpulseClient();
 
  const handleClick = async () => {
    const stats = await client.getStats();
    console.log(stats);
  };
 
  return <button onClick={handleClick}>Fetch Stats</button>;
}

Complete Example


import { MailpulseProvider, useStats, useCampaigns } from 'mailpulse/react';
 
function Dashboard() {
  const { data: stats, isLoading: statsLoading } = useStats();
  const { data: campaigns, isLoading: campaignsLoading } = useCampaigns();
 
  if (statsLoading || campaignsLoading) {
    return <div>Loading dashboard...</div>;
  }
 
  return (
    <div>
      <h1>Email Analytics Dashboard</h1>
 
      <section>
        <h2>Overview</h2>
        <div className="stats-grid">
          <div>Emails: {stats?.totalEmails}</div>
          <div>Opens: {stats?.totalOpens}</div>
          <div>Clicks: {stats?.totalClicks}</div>
          <div>Open Rate: {stats?.openRate}%</div>
        </div>
      </section>
 
      <section>
        <h2>Campaigns ({campaigns?.campaigns.length})</h2>
        <ul>
          {campaigns?.campaigns.map(c => (
            <li key={c.id}>{c.name}</li>
          ))}
        </ul>
      </section>
    </div>
  );
}
 
function App() {
  return (
    <MailpulseProvider apiKey={process.env.MAILPULSE_API_KEY!}>
      <Dashboard />
    </MailpulseProvider>
  );
}
 
export default App;