Documentation Index
Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
Use this file to discover all available pages before exploring further.
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: 'sender@yourdomain.com', // required
to: ['alice@example.com'], // required; array of recipients
subject: 'Your results are ready', // optional
reply_to: 'support@yourdomain.com', // optional
cc: ['manager@example.com'], // optional
bcc: ['audit@example.com'], // 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:unsub@yourdomain.com>', // 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: 'f@yourdomain.com', to: ['alice@example.com'], subject: 'Hi Alice', text_content: 'Hello Alice' }),
pbMail.message({ from: 'f@yourdomain.com', to: ['bob@example.com'], 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: 'appointments@yourclinic.com',
to: ['jane@example.com'],
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);
}