MC Mailer SDK for Node.js

A Node.js library for interacting with the MC Mailer API. This SDK provides a simple and convenient way to send emails and manage email operations through the MC Mailer service.

Installation

npm install mc-mailer-sdk-nodejs

Features

• Simple and intuitive API
• Configurable with API Key
• Support for sending emails
• Email status tracking
• Built-in error handling
• Promise-based async/await support

Usage

Basic Setup

const MailerService = require('mc-mailer-sdk-nodejs');

// Initialize the service with your API Key
const mailer = new MailerService({
  apiKey: 'your-api-key-here'
});

Custom Base URL (Optional)

If you need to use a custom API endpoint:

const mailer = new MailerService({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://custom-api.mcmailer.com'
});

Sending an Email

async function sendEmail() {
  try {
    const result = await mailer.sendEmail({
      to: '[email protected]',
      subject: 'Hello from MC Mailer SDK',
      body: 'This is a test email sent using the MC Mailer SDK',
      from: '[email protected]' // optional
    });
    
    console.log('Email sent successfully:', result);
  } catch (error) {
    console.error('Failed to send email:', error.message);
  }
}

sendEmail();

Checking Email Status

async function checkStatus(emailId) {
  try {
    const status = await mailer.getEmailStatus(emailId);
    console.log('Email status:', status);
  } catch (error) {
    console.error('Failed to get status:', error.message);
  }
}

checkStatus('email-id-123');

Making Custom API Calls

For custom API endpoints:

async function customRequest() {
  try {
    const result = await mailer.request('/custom/endpoint', {
      method: 'POST',
      body: {
        // your data here
      },
      headers: {
        // additional headers if needed
      }
    });
    
    console.log('Response:', result);
  } catch (error) {
    console.error('Request failed:', error.message);
  }
}

API Reference

Constructor

new MailerService(config)

Parameters:

• config (Object) - Configuration object
  • apiKey (string, required) - Your API Key for authentication
  • baseUrl (string, optional) - Custom base URL for the API (default: 'https://api.mcmailer.com')

Methods

sendEmail(emailData)

Sends an email through the MC Mailer API.

Parameters:

• emailData (Object)
  • to (string, required) - Recipient email address
  • subject (string, required) - Email subject
  • body (string, required) - Email body content
  • from (string, optional) - Sender email address

Returns: Promise - API response

getEmailStatus(emailId)

Gets the status of a sent email.

Parameters:

• emailId (string, required) - Email ID

Returns: Promise - Email status information

request(endpoint, options)

Makes a custom HTTP request to the API.

Parameters:

• endpoint (string, required) - API endpoint path
• options (Object, optional)
  • method (string) - HTTP method (default: 'GET')
  • body (Object) - Request body for POST/PUT requests
  • headers (Object) - Additional headers

Returns: Promise - API response

Error Handling

The SDK throws errors in the following cases:

1. Missing API Key: When initializing without an API Key
2. Network Errors: When unable to reach the API
3. API Errors: When the API returns an error response

Example error handling:

try {
  const result = await mailer.sendEmail(emailData);
} catch (error) {
  if (error.status) {
    // API error with status code
    console.error(`API Error ${error.status}:`, error.response);
  } else {
    // Network or other error
    console.error('Error:', error.message);
  }
}

Requirements

• Node.js 18.0.0 or higher (required for native fetch API support)

The library uses the native fetch API that is built into Node.js 18+. If you need to use this library with an older version of Node.js, you would need to install a fetch polyfill:

npm install node-fetch

And modify the import in lib/MailerService.js to use the polyfill. However, we recommend using Node.js 18+ for the best experience.

License

MIT

Author

Matias Camiletti

Repository

https://github.com/matiascamiletti/mc-mailer-sdk-nodejs