মূল অংশে যান
মেইলঘর

ইমেইল API

HTTPS বা SMTP দিয়ে ট্রানজ্যাকশনাল ইমেইল পাঠান। অনুরোধ ও উত্তর JSON-এ।

শুরু করা

প্রথম অনুরোধের আগে:

  1. একটি ইমেইল API প্ল্যান বেছে নিন।
  2. ইমেইল API › ডোমেইন-এ আপনার ডোমেইন যোগ করুন এবং তার SPF ও DKIM রেকর্ড প্রকাশ করুন।
  3. ইমেইল API › API কী-তে একটি কী তৈরি করুন।

বেস URL: https://api.mailghor.com/v1

প্রতিটি অনুরোধে আপনার কী দিয়ে প্রমাণ দিন: Authorization: Bearer mg_…

কী শুরু হয় mg_ দিয়ে। শুধু-পাঠানো কী দিয়ে পাঠানো যায়, কিন্তু ইমেইল দেখা বা বাতিল করা যায় না; সেজন্য পূর্ণ অ্যাক্সেসের কী ব্যবহার করুন।

ইমেইল পাঠানো

POST /emails — একটি ইমেইল সর্বোচ্চ ৫০ জন প্রাপককে পাঠায় (to, cc ও bcc মিলিয়ে)।

ফিল্ডধরনবিবরণ
fromstringপ্রেরক, যেমন "Acme <[email protected]>"। ডোমেইনটি যাচাই করা থাকতে হবে।
tostring | string[]প্রাপকেরা।
cc, bccstring | string[]ঐচ্ছিক কপি।
reply_tostring | string[]ঐচ্ছিক উত্তরের ঠিকানা।
subjectstringবিষয়।
html, textstringমূল লেখা; অন্তত একটি।
attachmentsobject[]{ filename, content (base64), content_type?, content_id? }; সব মিলিয়ে ২৫ MB পর্যন্ত।
headersobjectবাড়তি হেডার, যেমন { "X-Entity-Ref-ID": "123" }।
tagsobject[]{ name, value } জোড়া, লগ ও ওয়েবহুকে দেখা যায়।
scheduled_atISO 8601পরে পাঠান, ৩০ দিন পর্যন্ত।
curl
curl -X POST https://api.mailghor.com/v1/emails \
  -H "Authorization: Bearer $EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your order is on its way",
    "html": "<p>Thanks for shopping with us.</p>",
    "tags": [{ "name": "category", "value": "order" }]
  }'
Node.js
const res = await fetch("https://api.mailghor.com/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Acme <[email protected]>",
    to: "[email protected]",
    subject: "Your sign-in code",
    text: "Your code is 482913",
  }),
});
const { id } = await res.json();

উত্তর হলো { "id": "…" }: ইমেইলটি খুঁজতে বা ওয়েবহুক ইভেন্ট মেলাতে এটি রেখে দিন।

নিরাপদে আবার চেষ্টা করতে Idempotency-Key হেডার পাঠান: আগে ব্যবহার করা কী দিয়ে অনুরোধ এলে আবার পাঠানোর বদলে প্রথম ইমেইলের আইডি ফেরত দেওয়া হয়।

ব্যাচে পাঠানো

POST /emails/batch একটি অনুরোধে ১০০টি পর্যন্ত ইমেইল পাঠায়। প্রতিটির ফিল্ড একক ইমেইলের মতোই, শুধু attachments ও scheduled_at ছাড়া। হয় সবগুলো গৃহীত হয়, নয়তো একটিও না।

curl
curl -X POST https://api.mailghor.com/v1/emails/batch \
  -H "Authorization: Bearer $EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": [
    { "from": "[email protected]", "to": "[email protected]", "subject": "Hi A", "text": "…" },
    { "from": "[email protected]", "to": "[email protected]", "subject": "Hi B", "text": "…" }
  ] }'

# → { "data": [{ "id": "…" }, { "id": "…" }] }

দেখা ও বাতিল

GET /emails/{id} প্রত্যেক প্রাপকের অবস্থাসহ একটি ইমেইল দেখায়। POST /emails/{id}/cancel নির্ধারিত ইমেইল পাঠানোর আগে বাতিল করে।

curl
curl https://api.mailghor.com/v1/emails/4f1c2d8e-… \
  -H "Authorization: Bearer $EMAIL_API_KEY"

# Cancel a scheduled email:
curl -X POST https://api.mailghor.com/v1/emails/4f1c2d8e-…/cancel \
  -H "Authorization: Bearer $EMAIL_API_KEY"
অবস্থাবিবরণ
queued / scheduledগৃহীত, পাঠানোর অপেক্ষায়।
sentমেইল সার্ভারে দেওয়া হয়েছে।
deliveredপ্রাপকের সার্ভার গ্রহণ করেছে।
deferredপ্রাপকের সার্ভার পরে আবার চেষ্টা করতে বলেছে।
bouncedস্থায়ীভাবে ফেরত; ঠিকানাটি বাদের তালিকায় গেছে।
complainedস্প্যাম হিসেবে চিহ্নিত; ঠিকানাটি বাদের তালিকায় গেছে।
suppressedপাঠানো হয়নি: ঠিকানাটি আপনার বাদের তালিকায়।
failed / canceledপাঠানো হয়নি।

SMTP

SMTP দিয়ে পাঠাতে পারে এমন যেকোনো কিছু কোড না বদলেই ইমেইল API ব্যবহার করতে পারে।

SMTP
Host:      smtp.mailghor.com
Port:      587 (STARTTLS) or 465 (TLS)
Username:  ইমেইল API › SMTP-তে দেখানো
Password:  আপনার যেকোনো একটি API কী

SMTP দিয়ে পাঠানো মেসেজও একই যাচাইয়ের মধ্য দিয়ে যায় এবং একই লগে দেখা যায়। STARTTLS সহ পোর্ট ৫৮৭, বা TLS সহ ৪৬৫ ব্যবহার করুন।

ওয়েবহুক

ইমেইল API › ওয়েবহুক-এ এন্ডপয়েন্ট যোগ করুন। আপনার বাছাই করা প্রতিটি ইভেন্টের জন্য আমরা JSON বডিসহ একটি POST পাঠাই।

ইভেন্টবিবরণ
email.sentমেইল সার্ভারে দেওয়া হয়েছে।
email.deliveredপ্রাপকের সার্ভার গ্রহণ করেছে।
email.delivery_delayedআবার চেষ্টা করা হচ্ছে।
email.bouncedস্থায়ীভাবে ফেরত।
email.complainedপ্রাপক স্প্যাম হিসেবে চিহ্নিত করেছেন।
email.suppressedঠিকানা বাদের তালিকায় থাকায় বাদ।
email.failedপাঠানো যায়নি।
পেলোড
{
  "type": "email.delivered",
  "created_at": "2026-11-14T09:51:20.000Z",
  "data": {
    "email_id": "4f1c2d8e-…",
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your order is on its way",
    "recipients": ["[email protected]"],
    "tags": { "category": "order" }
  }
}

অনুরোধগুলো Standard Webhooks পদ্ধতিতে সই করা: webhook-signature মিলিয়ে দেখুন id.timestamp.body-এর HMAC-SHA256-এর সঙ্গে, এন্ডপয়েন্টের সিক্রেট দিয়ে।

সই যাচাই (Node.js)
import crypto from "node:crypto";

// secret: the whsec_… value from the panel. body: the raw request body (a string).
export function verify(secret, headers, body) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  return headers["webhook-signature"].split(" ").some((part) => part === `v1,${expected}`);
}

১০ সেকেন্ডের মধ্যে 2xx স্ট্যাটাস দিয়ে উত্তর দিন। নইলে আমরা প্রায় এক দিন ধরে আবার চেষ্টা করি; বারবার ব্যর্থ হলে এন্ডপয়েন্ট বন্ধ হয়, প্যানেল থেকে আবার চালু করতে পারবেন।

ত্রুটি ও সীমা

ত্রুটি আসে HTTP স্ট্যাটাস আর JSON বডিসহ: { "statusCode": 400, "message": "…" }। ত্রুটির বার্তা ইংরেজিতে; x-locale: bn হেডার দিলে বাংলায়।

কোডবিবরণ
400অনুরোধে কিছু ভুল আছে; বার্তায় তা বলা থাকে।
401API কী নেই বা সঠিক নয়।
403অনুমতি নেই: প্ল্যান নেই, ডোমেইন যাচাই হয়নি, কী দিয়ে এটি করা যায় না, বা পাঠানো বন্ধ।
404ইমেইলটি পাওয়া যায়নি।
413মেসেজটি অনেক বড়।
429মিনিটে অনেক বেশি ইমেইল, ওয়ার্ম-আপ সীমা, বা এই মাসের পরিমাণ শেষ।
5xxআমাদের দিকে কিছু ভুল হয়েছে; আবার চেষ্টা করুন।
  • প্রতি ইমেইলে ৫০ জন প্রাপক, প্রতি ব্যাচে ১০০টি ইমেইল পর্যন্ত।
  • সংযুক্তিসহ প্রতি ইমেইল ২৫ MB পর্যন্ত।
  • ৩০ দিন পর্যন্ত আগে থেকে সময় ঠিক করা যায়।
  • প্রতি মিনিটের হার ও মাসিক পরিমাণ আপনার প্ল্যানের ওপর নির্ভর করে।