حزمة Node.js

عميل Node.js الرسمي لواجهة برمجة تطبيقات Nateq. مبني على TypeScript، ويدعم كلاً من ESM و CommonJS، وبدون أي اعتماديات وقت التشغيل.

npm

@nateq/sdk

GitHub

الكود المصدري والمشكلات

المتطلبات

Node.js الإصدار 18 أو أحدث.

التثبيت

npm install @nateq/sdk

البدء السريع

أنشئ مفتاح API بنطاق emails:send، ثم ضعه في بيئتك:

NATEQ_API_KEY=tg_live_your_key_here

import { Nateq } from "@nateq/sdk";

const nateq = new Nateq(); // reads NATEQ_API_KEY

const result = await nateq.emails.send({
  toEmails: ["customer@example.com"],
  subject: "Welcome aboard",
  htmlBody: "<p>Thanks for signing up.</p>",
});

console.log(result.id);

المصادقة

تقرأ الحزمة NATEQ_API_KEY افتراضياً. مرّره صراحةً لتحميله من مدير أسرار، أو للتعامل مع أكثر من مؤسسة:

const nateq = new Nateq({ apiKey: await secrets.get("nateq_api_key") });

يتم التحقق من المفتاح محلياً قبل أي طلب، لذا يفشل المفتاح الخاطئ فوراً بدلاً من إرساله عبر الشبكة.

يحمل العميل مفتاح API الخاص بك، لذا لا تعرضه أبداً. تقوم console.log و JSON.stringify و util.inspect بإخفائه — لكن لا تُبطل ذلك بطباعة المفتاح مباشرةً.

النطاق	مطلوب لـ
`emails:send`	`emails.send()`
`emails:read`	`emails.get()` و `emails.list()`

إرسال البريد الإلكتروني

تُنجَز send() بمجرد قبول الواجهة للرسالة. أما التسليم فيحدث بعد ذلك — الوعد المُنجَز يعني أن Nateq تحمّلت مسؤولية الرسالة، لا أنها وصلت.

const result = await nateq.emails.send({
  toEmails: ["a@example.com", "b@example.com"],
  subject: "Quarterly update",
  htmlBody: "<p>Hello</p>",
  plainTextBody: "Hello",
  fromEmail: "hello@yourdomain.com", // must be a verified address
  fromName: "Acme Support",
  ccEmails: ["c@example.com"],
  bccEmails: ["d@example.com"],
  replyTo: "support@yourdomain.com",
  ticketId: "…",
  attachmentIds: ["…"],
  headers: { "X-Campaign": "q3" },
});

قدّم htmlBody أو plainTextBody أو كليهما. احذف fromEmail و emailAddressId لاستخدام عنوان مؤسستك الافتراضي المُوثَّق.

قراءة البريد الإلكتروني

const email = await nateq.emails.get(result.id);

email.status; // "delivered"
email.openCount;
email.bounceReason;

اعرض قائمة الرسائل المُرسلة، الأحدث أولاً:

const page = await nateq.emails.list({
  status: "bounced",
  toEmail: "customer@example.com",
  limit: 25,
});

for (const email of page.emails) {
  console.log(email.subject);
}

page.total;

القيمة الافتراضية لـ limit هي 50 والحد الأقصى 100.

الأخطاء

كل خطأ يرث من NateqError، لذا تكفي كتلة catch واحدة:

import {
  NateqError,
  NateqPermissionError,
  NateqRateLimitError,
  NateqValidationError,
} from "@nateq/sdk";

try {
  await nateq.emails.send({ /* … */ });
} catch (err) {
  if (err instanceof NateqValidationError) {
    // 400/422 — the request was wrong. Don't retry it unchanged.
  } else if (err instanceof NateqPermissionError) {
    // 403 — e.g. the key lacks emails:send
    err.code; // "INSUFFICIENT_SCOPE"
  } else if (err instanceof NateqRateLimitError) {
    err.retryAfter; // seconds
  } else if (err instanceof NateqError) {
    err.status;
    err.requestId; // quote this to support
  }
}

الخطأ	متى
`NateqValidationError`	400/422، أو وسائط خاطئة تُكتشف قبل أي طلب
`NateqAuthenticationError`	401 — مفتاح مفقود أو غير صالح أو مُلغى
`NateqPermissionError`	403 — المفتاح صالح لكنه غير مصرّح له
`NateqNotFoundError`	404
`NateqRateLimitError`	429 — يحمل `retryAfter`
`NateqServerError`	5xx
`NateqTimeoutError`	تجاوز الطلب المهلة المحددة
`NateqConnectionError`	DNS أو TLS أو المقبس أو انقطاع الاتصال
`NateqConfigurationError`	إعداد خاطئ للحزمة — يُطلَق قبل أي طلب

راجع الأخطاء لرموز الواجهة الأساسية.

إعادة المحاولة والإرسال المُكرر

تُعاد عمليات القراءة (get و list) تلقائياً عند انتهاء المهلة أو أخطاء 5xx أو فشل الاتصال، مع تراجع تدريجي يحترم Retry-After. أما send() فلا. لا تملك الواجهة مفتاح تكرار (idempotency key)، لذا فإن عملية إرسال تفشل بعد وصولها إلى الخادم قد تكون قد أُرسلت فعلاً. إعادتها قد تُرسل رسالتين إلى عميلك، والحزمة لن تتخذ هذا القرار نيابةً عنك. الاستثناء هو 429، الذي تُطلقه الواجهة قبل إرسال أي شيء — لذا تُعاد المحاولة، لأن التكرار مستحيل. إذا أطلقت send() خطأ NateqTimeoutError أو NateqServerError، فالنتيجة غير معروفة فعلاً. تحقق منها قبل إعادة المحاولة:

try {
  await nateq.emails.send({ toEmails: [user.email], subject, htmlBody });
} catch (err) {
  if (err instanceof NateqTimeoutError || err instanceof NateqServerError) {
    const recent = await nateq.emails.list({ toEmail: user.email, limit: 5 });
    // decide based on what's there
  }
}

الإعدادات

const nateq = new Nateq({
  apiKey: "tg_live_…",
  baseUrl: "https://api.nateq.io/api/v1",
  timeout: 30_000, // ms
  maxRetries: 2, // 0 disables
});

يجب أن يكون baseUrl عبر https، إلا إذا كان يشير إلى localhost للتطوير المحلي.

الاستخدام مع أُطر العمل

// app/api/welcome/route.ts
import { Nateq } from "@nateq/sdk";

const nateq = new Nateq();

export async function POST(request: Request) {
  const { email } = await request.json();

  await nateq.emails.send({
    toEmails: [email],
    subject: "Welcome aboard",
    htmlBody: "<p>Thanks for signing up.</p>",
  });

  return Response.json({ ok: true });
}

import { Module, Injectable } from "@nestjs/common";
import { Nateq } from "@nateq/sdk";

@Module({
  providers: [{ provide: Nateq, useFactory: () => new Nateq() }],
  exports: [Nateq],
})
export class NateqModule {}

@Injectable()
export class WelcomeMailer {
  constructor(private readonly nateq: Nateq) {}

  async send(email: string) {
    await this.nateq.emails.send({
      toEmails: [email],
      subject: "Welcome aboard",
      htmlBody: "<p>Thanks for signing up.</p>",
    });
  }
}

import express from "express";
import { Nateq } from "@nateq/sdk";

const nateq = new Nateq();
const app = express();

app.post("/welcome", express.json(), async (req, res, next) => {
  try {
    await nateq.emails.send({
      toEmails: [req.body.email],
      subject: "Welcome aboard",
      htmlBody: "<p>Thanks for signing up.</p>",
    });
    res.json({ ok: true });
  } catch (err) {
    next(err);
  }
});

أنشئ العميل مرة واحدة وأعد استخدامه. فهو عديم الحالة وآمن للمشاركة.

الإرسال داخل الطلب يربط زمن استجابتك بزمن استجابتنا. لأي شيء غير حرج، أرسل من مهمة في الخلفية أو من طابور بدلاً من ذلك.

ابدأ من هنا

حزم التطوير

المنصة

npm

GitHub

المتطلبات

التثبيت

البدء السريع

المصادقة

إرسال البريد الإلكتروني

قراءة البريد الإلكتروني

الأخطاء

إعادة المحاولة والإرسال المُكرر

الإعدادات

الاستخدام مع أُطر العمل

npm

GitHub

​المتطلبات

​التثبيت

​البدء السريع

​المصادقة

​إرسال البريد الإلكتروني

​قراءة البريد الإلكتروني

​الأخطاء

​إعادة المحاولة والإرسال المُكرر

​الإعدادات

​الاستخدام مع أُطر العمل

المتطلبات

التثبيت

البدء السريع

المصادقة

إرسال البريد الإلكتروني

قراءة البريد الإلكتروني

الأخطاء

إعادة المحاولة والإرسال المُكرر

الإعدادات

الاستخدام مع أُطر العمل