@kirimemail/smtp-sdk
Advanced tools
Node.js SDK for Kirim.Email SMTP API - A modern, fully-featured TypeScript SDK for managing SMTP credentials, domains, email sending, logs, and suppressions.
ky HTTP clientnpm install @kirimemail/smtp-sdk
The SDK uses Basic Authentication for all endpoints:
const { SmtpClient, CredentialsApi, DomainsApi } = require('@kirimemail/smtp-sdk');
// Initialize client with basic authentication
const client = new SmtpClient('your_username', 'your_token');
const credentialsApi = new CredentialsApi(client);
const domainsApi = new DomainsApi(client);
// List domains
const domains = await domainsApi.listDomains();
console.log(`Found ${domains.data.length} domains`);
// List credentials for a domain
const credentials = await credentialsApi.listCredentials('example.com');
console.log(`Found ${credentials.data.length} credentials`);
import {
SmtpClient,
CredentialsApi,
DomainsApi,
MessagesApi,
Credential,
Domain
} from '@kirimemail/smtp-sdk';
const client = new SmtpClient('username', 'token');
const credentialsApi = new CredentialsApi(client);
const domainsApi = new DomainsApi(client);
const messagesApi = new MessagesApi(client);
// Create a new credential
const credentialResult = await credentialsApi.createCredential('example.com', 'new_user');
if (credentialResult.success) {
const credential: Credential = credentialResult.data.credential;
console.log(`Created credential: ${credential.username}`);
console.log(`Password: ${credential.password}`); // Available only on create
}
// Send an email
const emailResult = await messagesApi.sendMessage('example.com', {
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Hello from Node.js SDK',
text: 'This is a test email sent using the KirimEmail Node.js SDK'
});
The main HTTP client for the Kirim.Email SMTP API.
new SmtpClient(username?, token?, baseUrl?)
username?: string - Username for basic authenticationtoken?: string - Token for basic authenticationbaseUrl?: string - Base URL for the API (default: https://smtp-app.kirim.email)get<T>(endpoint, params?, options?) - Make GET requestpost<T>(endpoint, data?, options?) - Make POST requestpostMultipart<T>(endpoint, data?, files?, options?) - Make POST request with multipart dataput<T>(endpoint, data?, options?) - Make PUT requestdelete<T>(endpoint, params?, options?) - Make DELETE requeststream<T>(endpoint, params?, options?) - Stream response dataAll API classes use Basic Authentication and follow the same pattern:
const client = new SmtpClient('username', 'token');
const api = new ApiClass(client);
Manage SMTP credentials:
listCredentials(domain, params?) - List domain credentialscreateCredential(domain, username) - Create new credentialgetCredential(domain, credentialId) - Get credential detailsdeleteCredential(domain, credentialId) - Delete credentialresetPassword(domain, credentialId) - Reset credential passwordManage domains and DNS settings:
listDomains(params?) - List all domainscreateDomain(options) - Create new domaingetDomain(domain) - Get domain detailsupdateDomain(domain, settings) - Update domain tracking settingsdeleteDomain(domain) - Delete domainsetupAuthDomain(domain, options) - Setup authentication domainverifyMandatoryRecords(domain) - Verify mandatory DNS recordsverifyAuthDomainRecords(domain) - Verify auth domain recordssetupTrackingDomain(domain, options) - Setup tracking domainverifyTrackingDomainRecords(domain) - Verify tracking domain recordsSend emails and manage messages:
sendMessage(domain, emailData) - Send simple emailsendMessageWithAttachments(domain, emailData, files) - Send email with attachmentssendBulkMessage(domain, emailData) - Send bulk emailsendTemplateMessage(domain, templateData) - Send template emailvalidateMessage(emailData) - Validate email datacreateFileUpload(filename, content, contentType?) - Create file upload objectRetrieve email logs and activity:
getLogs(domain, params?) - Get domain logs with filteringgetLogsByDateRange(domain, startDate, endDate, params?) - Get logs by date rangegetLogsByMessage(domain, messageGuid) - Get logs for specific messagestreamLogs(domain, params?) - Stream logs in real-timeLogFilterOptions:
start - Start date (string or Date)end - End date (string or Date)sender - Filter by sender emailrecipient - Filter by recipient emailevent_type - Filter by event type (queued, send, delivered, bounced, failed, opened, clicked, unsubscribed, temporary_fail, permanent_fail, deferred)tags - Filter by tags (partial match)limit, page, offset - Pagination optionsManage email suppressions:
getSuppressions(domain, params?) - Get all suppressionsgetUnsubscribeSuppressions(domain, params?) - Get unsubscribe suppressionsgetBounceSuppressions(domain, params?) - Get bounce suppressionsgetWhitelistSuppressions(domain, params?) - Get whitelist suppressionscreateWhitelistSuppression(domain, recipient) - Add to whitelistdeleteUnsubscribeSuppressions(domain, ids) - Delete unsubscribe suppressionsdeleteBounceSuppressions(domain, ids) - Delete bounce suppressionsdeleteWhitelistSuppressions(domain, ids) - Delete whitelist suppressionsValidate email addresses with comprehensive checks:
validateEmail(email) - Validate single emailvalidateEmailStrict(email) - Validate email with strict modevalidateEmailBulk(emails) - Validate multiple emails (max 100)validateEmailBulkStrict(emails) - Validate multiple emails with strict modeManage webhook configurations for event notifications:
listWebhooks(domain, params?) - List all webhookscreateWebhook(domain, options) - Create new webhookgetWebhook(domain, webhookGuid) - Get specific webhookupdateWebhook(domain, webhookGuid, options) - Update webhookdeleteWebhook(domain, webhookGuid) - Delete webhooktestWebhook(domain, webhookGuid) - Test webhook URLRepresents an SMTP credential with the following properties:
id?: number - Credential IDuserSmtpGuid?: string - User SMTP GUIDusername?: string - SMTP usernameisVerified?: boolean - Verification statusstatus?: boolean - Active statuspassword?: string - Password (available on create/reset)strengthInfo?: Record<string, any> - Password strength informationremoteSynced?: boolean - Remote sync statusgetCreatedDate(): Date | null - Get created date as Date objectisActive(): boolean - Check if credential is activeisActiveAndVerified(): boolean - Check if active and verifiedRepresents pagination metadata:
total?: number - Total number of itemsperPage?: number - Items per pagecurrentPage?: number - Current page numberlastPage?: number - Last page numberhasNextPage(): boolean - Check if more pages existhasPreviousPage(): boolean - Check if previous page existsgetNextPage(): number | null - Get next page numbergetSummary(): string - Get pagination summaryRepresents email validation result:
email: string - Validated email addressisValid: boolean - Whether email passed all validation checkserror: string | null - Error message if validation failedwarnings: string[] - Array of validation warningscached: boolean - Whether result was served from cachevalidatedAt: string - ISO timestamp of validationisSpamtrap: boolean - Whether email is likely a spamtrapspamtrapScore: number - Spamtrap probability score (0.0-1.0)Represents webhook configuration:
webhookGuid: string - Unique webhook identifier (UUID)userGuid: string - User GUID who owns webhookuserDomainGuid: string - Domain GUID associated with webhookuserSmtpGuid: string - SMTP configuration GUIDtype: 'queued' | 'send' | 'delivered' | 'bounced' | 'failed' | 'permanent_fail' | 'opened' | 'clicked' | 'unsubscribed' | 'temporary_fail' | 'deferred' - Event type that triggers webhookurl: string - URL endpoint for webhook eventsisDeleted: boolean - Whether webhook has been deletedcreatedAt: number - Creation timestampmodifiedAt: number - Last modified timestampThe SDK provides comprehensive error handling with custom exception classes:
try {
await credentialsApi.createCredential('example.com', 'test_user');
} catch (error) {
if (error.name === 'AuthenticationException') {
console.log('Authentication failed:', error.message);
} else if (error.name === 'ValidationException') {
console.log('Validation failed:', error.message);
if (error.hasErrors()) {
console.log('Field errors:', error.getErrorMessages());
}
} else if (error.name === 'NotFoundException') {
console.log('Resource not found:', error.message);
} else if (error.name === 'ServerException') {
console.log('Server error:', error.message);
} else {
console.log('API error:', error.message);
}
}
ApiException - Base exception for all API errorsAuthenticationException - Authentication errors (401, 403)ValidationException - Validation errors (400, 422)NotFoundException - Resource not found (404)ServerException - Server errors (500+)See the examples/ directory for complete usage examples:
node examples/comprehensive-example.js
const { DomainsApi } = require('@kirimemail/smtp-sdk');
const domainsApi = new DomainsApi(client);
// List all domains
const domains = await domainsApi.listDomains({ limit: 10 });
domains.data.forEach(domain => {
console.log(`Domain: ${domain.domain}, Verified: ${domain.isVerified}`);
});
// Create a new domain
const result = await domainsApi.createDomain({
domain: 'newdomain.com',
dkim_key_length: 2048
});
// Verify DNS records
const verification = await domainsApi.verifyMandatoryRecords('newdomain.com');
console.log('DKIM valid:', verification.data.records.dkim);
const { CredentialsApi } = require('@kirimemail/smtp-sdk');
const credentialsApi = new CredentialsApi(client);
// Create a new SMTP credential
const credential = await credentialsApi.createCredential('example.com', 'newsletter');
console.log(`Username: ${credential.data.credential.username}`);
console.log(`Password: ${credential.data.password}`); // Save this securely
// List all credentials
const credentials = await credentialsApi.listCredentials('example.com');
console.log(`Found ${credentials.data.length} credentials`);
// Reset password
const resetResult = await credentialsApi.resetPassword('example.com', credentialId);
console.log(`New password: ${resetResult.data.new_password}`);
const { MessagesApi } = require('@kirimemail/smtp-sdk');
const messagesApi = new MessagesApi(client);
// Send a simple email
const result = await messagesApi.sendMessage('example.com', {
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Welcome!',
text: 'Thank you for joining us.',
html: '<h1>Thank you for joining us!</h1><p>Welcome to our service.</p>'
});
// Send email with attachment
const fs = require('fs');
const attachment = messagesApi.createFileUpload(
'document.pdf',
fs.readFileSync('document.pdf'),
'application/pdf'
);
await messagesApi.sendMessageWithAttachments('example.com', {
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Document attached',
text: 'Please find the document attached.'
}, [attachment]);
// Send bulk email
await messagesApi.sendBulkMessage('example.com', {
from: 'newsletter@example.com',
to: ['user1@example.com', 'user2@example.com', 'user3@example.com'],
subject: 'Weekly Newsletter',
text: 'Here is your weekly newsletter...'
});
const { LogsApi } = require('@kirimemail/smtp-sdk');
const logsApi = new LogsApi(client);
// Get recent logs
const logs = await logsApi.getLogs('example.com', {
limit: 50,
start: '2024-01-01',
end: '2024-01-31'
});
logs.data.forEach(log => {
console.log(`${log.timestamp}: ${log.eventType} to ${log.recipient}`);
});
// Stream logs in real-time
for await (const log of logsApi.streamLogs('example.com', { limit: 100 })) {
console.log(`Live: ${log.eventType} - ${log.recipient}`);
}
const { SuppressionsApi } = require('@kirimemail/smtp-sdk');
const suppressionsApi = new SuppressionsApi(client);
// Get all suppressions
const suppressions = await suppressionsApi.getSuppressions('example.com');
console.log(`Total suppressions: ${suppressions.data.length}`);
// Get bounce suppressions
const bounces = await suppressionsApi.getBounceSuppressions('example.com');
// Add email to whitelist
await suppressionsApi.createWhitelistSuppression('example.com', 'important@client.com');
// Delete suppressions by IDs
await suppressionsApi.deleteBounceSuppressions('example.com', [1,2,3]);
const { EmailValidationApi } = require('@kirimemail/smtp-sdk');
const emailValidationApi = new EmailValidationApi(client);
// Validate a single email
const result = await emailValidationApi.validateEmail('user@example.com');
if (result.data.isValid) {
console.log('Email is valid');
console.log('Spamtrap score:', result.data.spamtrapScore);
} else {
console.log('Email is invalid:', result.data.error);
}
// Bulk validate emails
const bulkResult = await emailValidationApi.validateEmailBulk([
'user1@example.com',
'user2@example.com',
'invalid-email'
]);
console.log('Valid:', bulkResult.data.summary.valid);
console.log('Invalid:', bulkResult.data.summary.invalid);
console.log('Cached:', bulkResult.data.summary.cached);
const { WebhooksApi } = require('@kirimemail/smtp-sdk');
const webhooksApi = new WebhooksApi(client);
// List all webhooks
const webhooks = await webhooksApi.listWebhooks('example.com');
console.log(`Found ${webhooks.data.length} webhooks`);
// Create a webhook for delivery events
const webhook = await webhooksApi.createWebhook('example.com', {
type: 'delivered',
url: 'https://your-app.com/webhooks/delivered'
});
console.log('Webhook created:', webhook.data.webhookGuid);
// Update webhook
await webhooksApi.updateWebhook('example.com', webhook.data.webhookGuid, {
url: 'https://your-app.com/webhooks/updated'
});
// Test webhook
const test = await webhooksApi.testWebhook('example.com', webhook.data.webhookGuid);
console.log('Webhook test result:', test.message);
// Delete webhook
await webhooksApi.deleteWebhook('example.com', webhook.data.webhookGuid);
console.log('Webhook deleted');
npm run build
npm test
npm run lint
npm run lint:fix
MIT License - see LICENSE file for details.
See CHANGELOG.md for version history and changes.
FAQs
Node.js SDK for Kirim.Email SMTP API
We found that @kirimemail/smtp-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers 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.
Company News
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
Security News
NIST will stop enriching most CVEs under a new risk-based model, narrowing the NVD's scope as vulnerability submissions continue to surge.
Company News
/Security News
Socket is an initial recipient of OpenAI's Cybersecurity Grant Program, which commits $10M in API credits to defenders securing open source software.