@abdoseadaa/mail-tel

Client library for mail-tel API. Send Telegram alerts (text, media, HTML) with one config and simple send methods.

npm install @abdoseadaa/mail-tel

Function

configBot(params)

Creates a bot client. All send methods use the same API base and optional bot id.

import { configBot } from "@abdoseadaa/mail-tel";

const bot = configBot({
  id: "default",   // required — Telegram bot id (e.g. "default", "alerts")
  api: "https://mail.tel.api.gabster.ai",
});

bot.send.text(params)

Sends plain or HTML text to one or more chats.

await bot.send.text({
  to: [chatId1, chatId2],
  message: "Hello, how are you?",
});

bot.send.mediaUrl(params)

Sends a media group by URL (photos/videos). Telegram shows them as one album.

await bot.send.mediaUrl({
  to: [chatId1, groupId1],
  media: [
    { type: "photo", url: "https://example.com/1.jpg" },
    { type: "photo", url: "https://example.com/2.jpg" },
    { type: "video", url: "https://example.com/v.mp4" },
  ],
  message: "Caption (first item only)",
});

bot.send.photo(params)

Sends photo(s) via form-data (single file or album, up to 10). Use when you have buffers or blobs, not URLs.

await bot.send.photo({
  to: [chatId1, groupId1],
  files: [buffer1, buffer2],
  message: "Optional caption",
});

bot.send.video(params)

Sends video(s) via form-data (single file or album, up to 10).

await bot.send.video({
  to: [chatId1],
  files: [videoBuffer],
  message: "Optional caption",
});

bot.send.html(params)

Sends HTML content (Telegram subset: <b>, <i>, <code>, <a>, etc.).

await bot.send.html({
  to: [chatId1],
  html: "<b>Subject:</b> Hello<br/><p>Body</p>",
});

bot.health()

Calls GET /health (liveness). Returns { status, data } with data: { status?, timestamp? }.

const result = await bot.health();

bot.config()

Calls GET /config. Returns multi-bot config (defaultBot + bots with masked tokens).

const result = await bot.config();

bot.send.test(params?)

Sends a test message. Optional custom message and destinations.

await bot.send.test();
await bot.send.test({ to: [chatId1], message: "Custom test" });

Types

ConfigBotParams

interface ConfigBotParams {
  id: string;   // required — bot identifier on the server (e.g. "default", "alerts")
  api: string;  // base URL of the mail-tel API (no trailing slash)
}

SendTextParams

interface SendTextParams {
  to?: string | string[];
  message: string;
}

SendMediaUrlParams

interface SendMediaUrlParams {
  to?: string | string[];
  media: Array<{ type: "photo" | "video"; url: string }>;
  message?: string;
}

SendPhotoParams / SendVideoParams

interface SendPhotoParams {
  to?: string | string[];
  files: Buffer[] | Blob[] | Array<{ buffer: Buffer; filename?: string }>;
  message?: string;
}

MailTelResponse<T>

Unified shape for all responses:

interface MailTelResponse<T = unknown> {
  status: number;
  data: T | null;
  message?: string;
  errors?: Array<{ message: string; code?: string }>;
}

Examples

Basic text

const bot = configBot({ api: "https://mail.tel.api.gabster.ai" });
const result = await bot.send.text({
  to: ["-1001234567890"],
  message: "Hello!",
});
if (result.status === 200 && result.data) {
  console.log(result.data.sentTo);
}

Media by URL

const result = await bot.send.mediaUrl({
  to: [chatId1, chatId2],
  media: [
    { type: "photo", url: "https://example.com/1.jpg" },
    { type: "video", url: "https://example.com/v.mp4" },
  ],
  message: "Caption",
});

Handle errors

const result = await bot.send.text({ message: "Hi" });
if (result.status >= 400) {
  console.error(result.message ?? result.errors);
}

Photo from buffer (Node)

import { readFileSync } from "fs";
const buffer = readFileSync("./photo.jpg");
await bot.send.photo({
  to: [chatId],
  files: [buffer],
  message: "From file",
});

Dev Dependencies

| Package | Version | | ----------- | -------- | | @types/node | ^20.19.33 | | rimraf | ^5.0.5 | | typescript | ^5.5.3 |

Version History

| Version | Notes | | ------- | -------------- | | 1.0.0 | Initial release |