freely-email
Advanced tools
This Library is designed to make it easy for developers to send automated emails to multiple recipients. Minimum Node version 18 is required.
A simple, powerful, and scalable email-sending SDK native for Node.js, built with ❤️ by Harshit Keshari (Harshit107). Connects effortlessly to the FreelyEmail-API.
Version Requirement: Node.js >= 18.0.0 (Uses native fetch, 0 dependencies).
sequenceDiagram
participant App as Client App (Developer)
participant SDK as FreelyEmail Client SDK
participant NativeFetch as Node.js Native Fetch
participant Router as API /src/routes
participant Controller as API /src/controllers
participant Service as API /src/services
participant SMTP as Sendinblue SMTP
participant DB as MongoDB
App->>SDK: new FreelyEmailClient()
Note over App,SDK: Developer initiates the SDK (TypeScript supported)
App->>SDK: sendOTP({ sender: "auth", ... })
SDK->>NativeFetch: RequestManager checks payload, sends HTTP POST to /api/v1/emails/otp/send
NativeFetch->>Router: HTTP POST payload arrives
Router->>Controller: Route matches, passes to sendOtp() layer
Controller->>Controller: catchAsync & Validator check payload fields
alt If Validation Fails
Controller-->>SDK: 400 Bad Request
SDK-->>App: throws FreelyEmailAPIError
end
Controller->>Service: payload valid, sendMail(...)
Service->>SMTP: Connects via nodemailer & sends HTML email
SMTP-->>Service: msgId returned
Service->>DB: Log the transaction asynchronously (saveEmailRecord)
Controller-->>NativeFetch: 200 OK { success: true, messageId: ... }
NativeFetch-->>SDK: Parse JSON payload
SDK-->>App: Return Successful APIResponse
FreelyEmailClient and go.FreelyEmailAPIError) for robust backend integrations.npm install freely-email
Import and initialize the client. You can optionally pass a custom baseURL if you host the associated API yourself.
const { FreelyEmailClient } = require("freely-email");
// Default public API
const emailClient = new FreelyEmailClient();
// OR Custom Private API Server
// const emailClient = new FreelyEmailClient({ baseURL: "https://my-custom-email-api.com/api/v1/emails/" });
Send a customized email with optional HTML attachments.
async function notifyUser() {
try {
const response = await emailClient.sendEmail({
sender: "support-bot",
recipient: "user@example.com",
replyTo: "support@example.com",
app: "My Demo App",
subject: "Welcome Aboard!",
message: "This is a plain text message fallback.",
HTMLfile: "<html><body><h1>Welcome to My Demo App</h1></body></html>"
});
console.log("Success:", response.data.messageId);
} catch (error) {
console.error("Failed to send email:", error.message);
}
}
notifyUser();
Ask the API to securely generate a 6-digit OTP and email it to the user with a beautiful, modern HTML template.
async function requestOTP() {
const result = await emailClient.requestOTP({
sender: "Example Auth",
recipient: "user@example.com",
app: "Demo App",
subject: "Your Login Code",
withValidTime: 10 // Validity displayed as 10 minutes in the UI
});
console.log("OTP Sent!", result.data.messageId, result.data.otp);
}
Ping the backend server to ensure the email API is online.
emailClient.checkHealth()
.then(res => console.log(res.message))
.catch(err => console.error("API is down:", err));
The SDK exposes two custom error classes for clean try/catch checks:
FreelyEmailAPIError: HTTP issues (e.g., 400 Bad Request if missing fields, 500 API Crash).FreelyEmailValidationError: SDK-side malformed input errors.const { FreelyEmailClient, FreelyEmailAPIError } = require("freely-email");
try {
await emailClient.sendEmail({...});
} catch (err) {
if (err instanceof FreelyEmailAPIError) {
console.log("API Status Code:", err.status);
console.log("Details:", err.details);
}
}
FAQs
This Library is designed to make it easy for developers to send automated emails to multiple recipients. Minimum Node version 18 is required.
We found that freely-email 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.