Node.js/TypeScript SDK

# Install via npm
npm install @sparkmailr/nodejs-sdk

# Or via yarn
yarn add @sparkmailr/nodejs-sdk

const { SparkMailrClient } = require('@sparkmailr/nodejs-sdk');

// Initialize client
const client = new SparkMailrClient({
    apiKey: 'your-api-key'
});

// Send email
async function sendEmail() {
    try {
        const response = await client.emails.send({
            to: ['user@example.com'],
            from: 'noreply@yourapp.com',
            subject: 'Welcome to SparkMailr!',
            html: '<h1>Hello World</h1>',
            text: 'Hello World'
        });
        
        console.log(`Email sent: ${response.id}`);
    } catch (error) {
        console.error('Email failed:', error.message);
    }
}

sendEmail();

import { SparkMailrClient, SendEmailRequest, EmailResponse } from '@sparkmailr/nodejs-sdk';

// Initialize client with full type safety
const client = new SparkMailrClient({
    apiKey: process.env.SPARKMAILR_API_KEY!,
    timeout: 30000,
    maxRetries: 3
});

// Send email with types
async function sendTypedEmail(): Promise<EmailResponse> {
    const request: SendEmailRequest = {
        to: ['user@example.com'],
        from: 'noreply@yourapp.com',
        subject: 'Welcome to SparkMailr!',
        html: '<h1>Hello World</h1>',
        text: 'Hello World'
    };
    
    const response = await client.emails.send(request);
    console.log(`Email sent: ${response.id}`);
    return response;
}

import { SparkMailrClient, SparkMailrConfig } from '@sparkmailr/nodejs-sdk';

const config: SparkMailrConfig = {
    apiKey: 'your-api-key',
    baseUrl: 'https://api.sparkmailr.com',  // Optional
    timeout: 30000,                         // Request timeout (ms)
    maxRetries: 3,                          // Max retry attempts
    retryDelay: 1000,                       // Delay between retries (ms)
    debug: process.env.NODE_ENV === 'development',
    headers: {                              // Custom headers
        'X-Custom-Header': 'value'
    }
};

const client = new SparkMailrClient(config);

import { TemplateEmailRequest } from '@sparkmailr/nodejs-sdk';

const templateRequest: TemplateEmailRequest = {
    to: ['user@example.com'],
    from: 'noreply@yourapp.com',
    templateId: 'welcome-template',
    templateData: {
        name: 'John Doe',
        activationLink: 'https://app.example.com/activate/123',
        company: 'Acme Corp'
    }
};

const response = await client.emails.send(templateRequest);
console.log(`Template email sent: ${response.id}`);

import { BulkEmailRequest } from '@sparkmailr/nodejs-sdk';

const bulkRequest: BulkEmailRequest = {
    from: 'newsletter@yourapp.com',
    templateId: 'newsletter-template',
    recipients: [
        {
            to: 'user1@example.com',
            templateData: { name: 'User 1', customField: 'value1' }
        },
        {
            to: 'user2@example.com', 
            templateData: { name: 'User 2', customField: 'value2' }
        }
    ]
};

const bulkResponse = await client.emails.sendBulk(bulkRequest);
console.log(`Bulk batch: ${bulkResponse.batchId}`);

// Get email status
const status = await client.emails.getStatus('em_1234567890');
console.log(`Status: ${status.status}`);
console.log(`Delivered: ${status.deliveredAt}`);

// Get analytics
const analytics = await client.analytics.getEmailStats({
    startDate: '2025-01-01',
    endDate: '2025-01-31'
});

console.log(`Sent: ${analytics.sent}`);
console.log(`Delivery Rate: ${analytics.deliveryRate}%`);
console.log(`Open Rate: ${analytics.openRate}%`);

import {
    SparkMailrError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    NetworkError
} from '@sparkmailr/nodejs-sdk';

async function sendWithErrorHandling() {
    try {
        const response = await client.emails.send({
            to: ['invalid-email'],
            from: 'noreply@yourapp.com',
            subject: 'Test Email'
        });
    } catch (error) {
        if (error instanceof AuthenticationError) {
            console.error('Authentication failed - check API key');
        } else if (error instanceof RateLimitError) {
            console.error(`Rate limited - retry after ${error.retryAfter}s`);
        } else if (error instanceof ValidationError) {
            console.error('Validation failed:', error.validationErrors);
        } else if (error instanceof NetworkError) {
            console.error('Network error - check connectivity');
        } else if (error instanceof SparkMailrError) {
            console.error(`SparkMailr error: ${error.message}`);
        } else {
            console.error('Unexpected error:', error);
        }
    }
}

import express from 'express';
import { SparkMailrClient } from '@sparkmailr/nodejs-sdk';

const app = express();
app.use(express.json());

// Initialize SparkMailr client
const sparkMailr = new SparkMailrClient({
    apiKey: process.env.SPARKMAILR_API_KEY!
});

// Contact form endpoint
app.post('/api/contact', async (req, res) => {
    try {
        const { name, email, message } = req.body;
        
        // Send notification email
        const response = await sparkMailr.emails.send({
            to: ['admin@yourapp.com'],
            from: 'noreply@yourapp.com',
            subject: 'New Contact Form Submission',
            html: `
                <h2>New Contact Form Submission</h2>
                <p><strong>Name:</strong> ${name}</p>
                <p><strong>Email:</strong> ${email}</p>
                <p><strong>Message:</strong></p>
                <p>${message}</p>
            `
        });
        
        res.json({ 
            success: true, 
            emailId: response.id 
        });
    } catch (error) {
        console.error('Failed to send contact email:', error);
        res.status(500).json({ 
            success: false, 
            error: 'Failed to send message' 
        });
    }
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

// lib/sparkmailr.ts
import { SparkMailrClient } from '@sparkmailr/nodejs-sdk';

export const sparkMailr = new SparkMailrClient({
    apiKey: process.env.SPARKMAILR_API_KEY!
});

// pages/api/send-email.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { sparkMailr } from '../../lib/sparkmailr';

export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
) {
    if (req.method !== 'POST') {
        return res.status(405).json({ error: 'Method not allowed' });
    }
    
    try {
        const { to, subject, html } = req.body;
        
        const response = await sparkMailr.emails.send({
            to: [to],
            from: 'noreply@yourapp.com',
            subject,
            html
        });
        
        res.status(200).json({ 
            success: true, 
            emailId: response.id 
        });
    } catch (error) {
        console.error('Email send failed:', error);
        res.status(500).json({ 
            success: false, 
            error: 'Failed to send email' 
        });
    }
}

// components/ContactForm.tsx
import { useState } from 'react';

export default function ContactForm() {
    const [loading, setLoading] = useState(false);
    
    const handleSubmit = async (e: React.FormEvent) => {
        e.preventDefault();
        setLoading(true);
        
        try {
            const response = await fetch('/api/send-email', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    to: 'admin@yourapp.com',
                    subject: 'Contact Form Submission',
                    html: '<p>New message from contact form</p>'
                })
            });
            
            if (response.ok) {
                alert('Message sent successfully!');
            }
        } finally {
            setLoading(false);
        }
    };
    
    return (
        <form onSubmit={handleSubmit}>
            <button type="submit" disabled={loading}>
                {loading ? 'Sending...' : 'Send Message'}
            </button>
        </form>
    );
}

// __tests__/sparkmailr.test.ts
import { SparkMailrClient } from '@sparkmailr/nodejs-sdk';
import nock from 'nock';

describe('SparkMailr Integration', () => {
    let client: SparkMailrClient;
    
    beforeEach(() => {
        client = new SparkMailrClient({ 
            apiKey: 'test-api-key',
            baseUrl: 'https://api.test.com'
        });
    });
    
    afterEach(() => {
        nock.cleanAll();
    });
    
    it('should send email successfully', async () => {
        // Mock API response
        nock('https://api.test.com')
            .post('/v1/emails/send')
            .reply(200, {
                id: 'em_123456',
                status: 'queued'
            });
        
        const response = await client.emails.send({
            to: ['test@example.com'],
            from: 'noreply@test.com',
            subject: 'Test Email',
            html: '<p>Test content</p>'
        });
        
        expect(response.id).toBe('em_123456');
        expect(response.status).toBe('queued');
    });
    
    it('should handle rate limit error', async () => {
        nock('https://api.test.com')
            .post('/v1/emails/send')
            .reply(429, {
                error: 'Rate limit exceeded',
                retry_after: 60
            });
        
        await expect(client.emails.send({
            to: ['test@example.com'],
            from: 'noreply@test.com',
            subject: 'Test'
        })).rejects.toThrow('Rate limit exceeded');
    });
});

// Run tests
// npm test