@venmail/vsm

Send emails with Venmail - Simple & Fast

Installation

npm

npm install @venmail/vsm

yarn

yarn add @venmail/vsm

pnpm

pnpm add @venmail/vsm

Get started in seconds with Venmail's email SDK.

1. Get Your API Token

Venmail uses two authentication methods - get your JWT token to send emails.

🔑 Authentication Explained

Venmail uses device authentication to get JWT tokens for API access:

  • • Device Token + Exchange Code → JWT Token
  • • JWT Token used for all email sending API calls
  • • No username/password authentication

🔐 Step 1: Get Device Credentials

Get your device token and exchange code from Venmail admin panel:

import { VenmailAPI } from '@venmail/vsm';

// Step 1: Authenticate with device credentials
const api = new VenmailAPI({
  baseUrl: 'https://m.venmail.io',
  deviceToken: 'your-device-token',     // From Venmail admin
  exchangeCode: 'your-exchange-code'     // One-time code from admin
});

// Step 2: Get your JWT token
const authResult = await api.authenticate();
console.log('JWT Token:', authResult.token);
console.log('User:', authResult.user);

✅ Done! You now have a JWT token for API calls.

💡 Tip: Store the JWT token securely and reuse it for 1 hour.

2. Send Email

Use your JWT token to send emails via MailAPIController endpoints.

📧 Send Email with JWT Token

All email sending endpoints use JWT Bearer token authentication:

import { VenmailAPI } from '@venmail/vsm';

// Use your JWT token from step 1
const api = new VenmailAPI({
  baseUrl: 'https://m.venmail.io',
  token: 'your-jwt-token'  // JWT Bearer token
});

// Send an email - calls MailAPIController endpoints
const result = await api.sendEmail({
  to: 'hello@example.com',
  subject: 'Hello from Venmail!',
  html: '
This email was sent using @venmail/vsm
',
  text: 'This email was sent using @venmail/vsm'
});

console.log('Email sent:', result.messageId);
console.log('Status:', result.status);

✅ Success! Email sent via MailAPIController.

🔧 Backend: Uses JWT Bearer token authentication.

Handle Webhooks

Listen for email events like deliveries, bounces, and opens.

import { venmailIntegrationWebhook } from '@venmail/vsm';
import express from 'express';

const app = express();

// Handle Venmail webhooks
app.post('/webhooks/venmail', venmailIntegrationWebhook({
  secret: process.env.VENMAIL_WEBHOOK_SECRET!,
  onEvent: async (event) => {
    console.log(`Event: ${event.event_type}`);
    
    if (event.event_type === 'MessageDelivered') {
      console.log('Email was delivered!');
    }
    
    if (event.event_type === 'MessageBounced') {
      console.log('Email bounced - handle it!');
    }
  }
}));

app.listen(3000);

Send Attachments

Easily attach files to your emails.

import { VenmailAPI } from '@venmail/vsm';

const api = new VenmailAPI({
  baseUrl: 'https://m.venmail.io',
  token: 'your-jwt-token'
});

// Send email with attachments
await api.sendEmail({
  to: 'client@example.com',
  subject: 'Your Document',
  html: '
Please find the attached document.
',
  attachments: [
    {
      filename: 'document.pdf',
      content: base64FileContent,
      contentType: 'application/pdf'
    }
  ]
});

Authentication Methods

🔐 Get JWT Token

Device authentication for API access:

  • • Method: Device Token + Exchange Code
  • • Endpoint: POST /api/v1/auth
  • • Controller: MailAPIController@auth
  • • Result: JWT Bearer token (1 hour TTL)

📧 Send Emails

JWT authentication for email operations:

  • • Method: JWT Bearer Token
  • • Header: Authorization: Bearer {token}
  • • Endpoints: MailAPIController methods
  • • Features: HTML + text + attachments

API Endpoints Overview

Purpose Authentication Controller
Get JWT Token Device Token + Exchange Code MailAPIController@auth
Send Email JWT Bearer Token MailAPIController send methods
Handle Webhooks Network-level / Shared Secret Various webhook handlers
File Management MarketAuth (Device Token) AppFileAPIController