Official Node.js SDK for GetMailer - Modern email delivery for developers.
npm install getmailer
# or
yarn add getmailer
# or
pnpm add getmailer
import { GetMailer } from 'getmailer';
const client = new GetMailer({
apiKey: 'gm_xxxxx',
});
// Send an email
await client.emails.send({
from: 'hello@example.com',
to: 'user@example.com',
subject: 'Hello from GetMailer!',
html: '<p>Welcome to GetMailer</p>',
});
const client = new GetMailer({
apiKey: 'gm_xxxxx', // Required: Your API key
baseUrl: 'https://...', // Optional: Custom API base URL
timeout: 30000, // Optional: Request timeout in ms (default: 30000)
maxRetries: 3, // Optional: Max retry attempts (default: 3)
debug: false, // Optional: Enable debug logging (default: false)
});
const response = await client.emails.send({
from: 'hello@example.com',
to: ['user1@example.com', 'user2@example.com'],
subject: 'Hello',
html: '<h1>Welcome!</h1>',
text: 'Welcome!',
cc: 'cc@example.com',
bcc: 'bcc@example.com',
replyTo: 'reply@example.com',
tags: ['welcome', 'onboarding'],
headers: { 'X-Custom': 'value' },
});
console.log(response.id); // Email ID
await client.emails.sendTemplate({
from: 'hello@example.com',
to: 'user@example.com',
templateId: 'welcome-email',
variables: {
name: 'John Doe',
url: 'https://example.com/verify',
},
});
await client.emails.sendBatch({
name: 'Weekly Newsletter',
from: 'news@example.com',
templateId: 'newsletter',
recipients: [
{ to: 'user1@example.com', variables: { name: 'Alice' } },
{ to: 'user2@example.com', variables: { name: 'Bob' } },
'user3@example.com',
],
});
await client.emails.send({
from: 'hello@example.com',
to: 'user@example.com',
subject: 'Scheduled Email',
html: '<p>This will be sent later</p>',
scheduledAt: new Date('2024-12-25T10:00:00Z').toISOString(),
});
// Add a domain
const { domain } = await client.domains.add({
name: 'example.com',
});
// List domains
const { domains } = await client.domains.list();
// Verify domain
await client.domains.verify({ domainId: domain.id });
// Delete domain
await client.domains.delete(domain.id);
// Create template
const template = await client.templates.create({
name: 'Welcome Email',
subject: 'Welcome {{name}}!',
html: '<h1>Hello {{name}}</h1>',
});
// List templates
const { templates } = await client.templates.list();
// Get template
const tmpl = await client.templates.get(template.id);
// Update template
await client.templates.update({
id: template.id,
subject: 'Welcome {{name}} to GetMailer!',
});
// Delete template
await client.templates.delete(template.id);
// Create audience
const { audience } = await client.audiences.create({
name: 'Newsletter Subscribers',
description: 'Users who opted in for newsletters',
});
// Add contacts
await client.audiences.contacts(audience.id).add({
email: 'user@example.com',
firstName: 'John',
lastName: 'Doe',
customFields: { source: 'website' },
});
// Bulk add contacts
await client.audiences.contacts(audience.id).addBulk({
contacts: [
{ email: 'user1@example.com', firstName: 'Alice' },
{ email: 'user2@example.com', firstName: 'Bob' },
],
});
// List contacts
const { contacts } = await client.audiences.contacts(audience.id).list({
limit: 50,
subscribed: true,
search: 'john',
});
// Remove contacts
await client.audiences.contacts(audience.id).remove({
emails: ['user@example.com'],
});
// Create webhook
const webhook = await client.webhooks.create({
name: 'My Webhook',
url: 'https://example.com/webhook',
events: ['SENT', 'DELIVERED', 'BOUNCED'],
});
console.log(webhook.secret); // Use this to verify webhook signatures
// List webhooks
const { webhooks } = await client.webhooks.list();
// Update webhook
await client.webhooks.update({
id: webhook.id,
enabled: false,
});
// Delete webhook
await client.webhooks.delete(webhook.id);
// Validate single email
const result = await client.validation.verify('user@example.com');
if (result.valid) {
console.log('Email is valid');
console.log('Risk level:', result.details.risk);
}
// Batch validation
const results = await client.validation.verifyBatch([
'user1@example.com',
'user2@example.com',
'invalid@',
]);
console.log(`Valid: ${results.summary.valid}/${results.summary.total}`);
import {
GetMailerError,
AuthenticationError,
RateLimitError,
ValidationError,
} from 'getmailer';
try {
await client.emails.send({ /* ... */ });
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof RateLimitError) {
console.error('Rate limited, retry after:', error.retryAfter);
} else if (error instanceof ValidationError) {
console.error('Validation error:', error.message);
} else if (error instanceof GetMailerError) {
console.error('API error:', error.status, error.message);
}
}
// List with pagination
let cursor: string | null = null;
do {
const response = await client.emails.list({
limit: 100,
cursor,
});
for (const email of response.emails) {
console.log(email.id, email.subject);
}
cursor = response.nextCursor;
} while (cursor);
Use idempotency keys to safely retry requests:
const idempotencyKey = `email-${Date.now()}-${Math.random()}`;
await client.emails.send({
from: 'hello@example.com',
to: 'user@example.com',
subject: 'Important Email',
html: '<p>This email will only be sent once</p>',
// Idempotency key in request headers
});
new GetMailer(config) - Create a new client instanceclient.emails.send(request) - Send a single emailclient.emails.sendTemplate(request) - Send email with templateclient.emails.sendBatch(request) - Send batch emailsclient.emails.get(emailId) - Get email detailsclient.emails.list(params?) - List emailsclient.emails.listBatches(params?) - List batch jobsclient.emails.getBatch(batchId) - Get batch detailsclient.emails.cancelBatch(batchId) - Cancel a batchclient.domains.list() - List all domainsclient.domains.add(request) - Add a new domainclient.domains.verify(request) - Verify domain DNS recordsclient.domains.delete(domainId) - Delete a domainclient.templates.list(params?) - List all templatesclient.templates.get(templateId) - Get template detailsclient.templates.create(request) - Create a new templateclient.templates.update(request) - Update a templateclient.templates.delete(templateId) - Delete a templateclient.audiences.list(params?) - List all audiencesclient.audiences.get(audienceId) - Get audience detailsclient.audiences.create(request) - Create a new audienceclient.audiences.delete(audienceId) - Delete an audienceclient.audiences.contacts(audienceId).list(params?) - List contactsclient.audiences.contacts(audienceId).add(contact) - Add a contactclient.audiences.contacts(audienceId).addBulk(request) - Bulk add contactsclient.audiences.contacts(audienceId).remove(request) - Remove contactsclient.webhooks.list() - List all webhooksclient.webhooks.create(request) - Create a new webhookclient.webhooks.update(request) - Update a webhookclient.webhooks.delete(webhookId) - Delete a webhookclient.validation.verify(email) - Validate a single emailclient.validation.verifyBatch(emails) - Validate multiple emailsThe SDK is written in TypeScript and provides full type definitions:
import type {
SendEmailRequest,
EmailResponse,
Template,
Audience,
Contact,
} from 'getmailer';
GetMailerError - Base error classAuthenticationError - Invalid API key (401)RateLimitError - Rate limit exceeded (429)ValidationError - Invalid request data (400)NotFoundError - Resource not found (404)ServerError - Server error (5xx)NetworkError - Network/timeout errorMIT
For issues and questions:
FAQs
Official Node.js SDK for GetMailer - Modern email delivery for developers
We found that getmailer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.