​
Getting Started with Mailblock SDK

This guide will help you get up and running with the Mailblock SDK in just a few minutes.

​
Prerequisites

  • Node.js 14 or higher
  • A Mailblock API key MailBlock

​
Installation

Install the SDK using npm: 
npm install mailblock
Or using yarn: 
yarn add mailblock

​
Basic Setup

Import and initialize the SDK with your API key: 
import Mailblock from 'mailblock';

const client = new Mailblock('your-api-key-here');

​
Sending Your First Email

Here’s how to send a simple email: 
const result = await client.sendEmail({
  to: 'recipient@example.com',
  from: 'sender@yourdomain.com',
  subject: 'Hello from Mailblock!',
  text: 'This is my first email using the Mailblock SDK.'
});

if (result.success) {
  console.log('Email sent successfully!');
  console.log('Email ID:', result.data.id);
} else {
  console.error('Failed to send email:', result.error);
}

​
Using Method Chaining

The SDK also supports a fluent, chainable API: 
const result = await client.email()
  .to('recipient@example.com')
  .from('sender@yourdomain.com')
  .subject('Hello from Mailblock!')
  .text('This email was sent using method chaining.')
  .send();

​
Sending HTML Emails

You can send rich HTML emails instead of plain text: 
const result = await client.sendEmail({
  to: 'recipient@example.com',
  from: 'sender@yourdomain.com',
  subject: 'Welcome to Our Service',
  html: `
    <h1>Welcome!</h1>
    <p>Thanks for signing up. We're excited to have you on board.</p>
    <a href="https://yoursite.com/dashboard">Get Started</a>
  `
});

​
Scheduling Emails

Schedule emails to be sent at a future date and time: 
// Schedule email for 1 hour from now
const scheduledTime = new Date(Date.now() + 60 * 60 * 1000);

const result = await client.sendEmail({
  to: 'recipient@example.com',
  from: 'sender@yourdomain.com',
  subject: 'Scheduled Email',
  text: 'This email was scheduled to be sent later.',
  scheduledAt: scheduledTime
});

if (result.success) {
  console.log('Email scheduled successfully!');
}
You can also use ISO date strings: 
const result = await client.sendEmail({
  to: 'recipient@example.com',
  from: 'sender@yourdomain.com',
  subject: 'Scheduled Email',
  text: 'This email was scheduled using an ISO string.',
  scheduledAt: '2024-12-25T09:00:00.000Z' // Christmas morning
});

​
Environment Configuration

For production applications, use environment variables for your API key: 
// .env file
MAILBLOCK_API_KEY=your-api-key-here

// Your application
import Mailblock from 'mailblock';

const client = new Mailblock(process.env.MAILBLOCK_API_KEY);

​
Debug Mode

Enable debug mode during development to see detailed logs: 
const client = new Mailblock('your-api-key', { 
  debug: true 
});

// Now you'll see detailed logs for all API calls
const result = await client.sendEmail({
  to: 'test@example.com',
  from: 'sender@yourdomain.com',
  subject: 'Debug Test',
  text: 'Testing with debug mode enabled'
});
Debug logs include:
  • Request details and timing
  • API responses
  • Error information
  • Performance metrics

​
TypeScript Support

The SDK includes full TypeScript support out of the box: 
import Mailblock, { EmailOptions, EmailResponse } from 'mailblock';

const client: Mailblock = new Mailblock('your-api-key');

const emailOptions: EmailOptions = {
  to: 'recipient@example.com',
  from: 'sender@yourdomain.com',
  subject: 'TypeScript Email',
  text: 'This email was sent with full type safety!'
};

const result: EmailResponse = await client.sendEmail(emailOptions);

​
Error Handling

The SDK uses a consistent response format that makes error handling straightforward: 
const result = await client.sendEmail({
  to: 'invalid-email', // This will cause a validation error
  from: 'sender@yourdomain.com',
  subject: 'Test',
  text: 'Test message'
});

if (!result.success) {
  console.log('Error Type:', result.errorType); // 'VALIDATION_ERROR'
  console.log('Error Message:', result.error);  // 'Invalid recipient email address: invalid-email'
  console.log('Suggestion:', result.suggestion); // Helpful tip for fixing the error
  console.log('Request ID:', result.requestId);  // For support/debugging
}

​
Next Steps

Now that you’ve sent your first email, you might want to:

​
Need Help?