Email client

Full reference for the Paubox Node.js SDK email service: building messages, sending email, tracking delivery, dynamic templates, and error handling.

Create the service

const pbMail  = require('paubox-node');

// Read credentials from environment variables
const service = pbMail.emailService();

// Or pass credentials directly
const service = pbMail.emailService({ apiKey: 'YOUR_API_KEY', apiUsername: 'YOUR_USERNAME' });

Build a message

const message = pbMail.message({
  from:         '[e-mail]',  // required
  to:           ['[e-mail]'],    // required; array of recipients
  subject:      'Your results are ready', // optional
  reply_to:     '[e-mail]', // optional
  cc:           ['[e-mail]'],  // optional
  bcc:          ['[e-mail]'],    // optional
  text_content: 'Plain text body.',       // at least one of text/html required
  html_content: '<p>HTML body.</p>',      // optional; auto base64-encoded
  allowNonTLS:  false,                    // optional; default false
  forceSecureNotification: false,         // optional; default false
  custom_headers: { 'X-Custom': 'value' },// optional; keys must start with X-
  list_unsubscribe:      '<mailto:[e-mail]>', // optional
  list_unsubscribe_post: 'List-Unsubscribe=One-Click',   // optional
  attachments: [attachment]               // optional; see below
});

Attachments

const fs = require('fs');

const attachment = {
  fileName:    'report.pdf',
  contentType: 'application/pdf',
  content:     fs.readFileSync('report.pdf').toString('base64')
};

Send a message

const response = await service.sendMessage(message);
console.log('Tracking ID:', response.sourceTrackingId);

Send bulk messages

Send up to 50 messages in a single API call. Each message gets its own tracking ID.

const messages = [
  pbMail.message({ from: '[e-mail]', to: ['[e-mail]'], subject: 'Hi Alice', text_content: 'Hello Alice' }),
  pbMail.message({ from: '[e-mail]', to: ['[e-mail]'],   subject: 'Hi Bob',   text_content: 'Hello Bob' }),
];

const response = await service.sendBulkMessages(messages);

for (const msg of response.messages) {
  console.log('Tracking ID:', msg.sourceTrackingId);
}

Check delivery status

const disposition = await service.getEmailDisposition(sourceTrackingId);

for (const delivery of disposition.data.message.message_deliveries) {
  console.log(`${delivery.recipient} → ${delivery.status.deliveryStatus}`);
}

Common deliveryStatus values: delivered, opened, failed, pending. The openedStatus field defaults to "unopened" if not yet set.

Dynamic templates

Templates use Handlebars syntax ({{variable_name}}). Template content can be a string, Buffer, or readable Stream.

Create a template

const fs = require('fs');

const response = await service.createDynamicTemplate(
  'appointment-confirmation',
  fs.createReadStream('templates/appointment.html')
);

List templates

const templates = await service.listDynamicTemplates();
for (const t of templates) {
  console.log(t.id, t.name);
}

Get a template

const template = await service.getDynamicTemplate(templateId);

Update a template

Pass null for fields you want to leave unchanged:

await service.updateDynamicTemplate(
  templateId,
  'appointment-confirmation-v2', // new name, or null to keep current
  null                            // content unchanged
);

Delete a template

await service.deleteDynamicTemplate(templateId);

Send a templated message

const message = pbMail.templatedMessage({
  from:            '[e-mail]',
  to:              ['[e-mail]'],
  subject:         'Your appointment is confirmed',
  template_name:   'appointment-confirmation',
  template_values: {
    first_name: 'Jane',
    date:       '2024-03-15',
    time:       '2:00 PM'
  }
});

const response = await service.sendTemplatedMessage(message);

Error handling

All service methods return Promises and reject on API errors. Use try/catch in async functions:

try {
  const response = await service.sendMessage(message);
  console.log('Sent:', response.sourceTrackingId);
} catch (err) {
  console.error('Send failed:', err.message);
}