ইমেইল API
HTTPS বা SMTP দিয়ে ট্রানজ্যাকশনাল ইমেইল পাঠান। অনুরোধ ও উত্তর JSON-এ।
শুরু করা
প্রথম অনুরোধের আগে:
- একটি ইমেইল API প্ল্যান বেছে নিন।
- ইমেইল API › ডোমেইন-এ আপনার ডোমেইন যোগ করুন এবং তার SPF ও DKIM রেকর্ড প্রকাশ করুন।
- ইমেইল API › API কী-তে একটি কী তৈরি করুন।
বেস URL: https://api.mailghor.com/v1
প্রতিটি অনুরোধে আপনার কী দিয়ে প্রমাণ দিন: Authorization: Bearer mg_…
কী শুরু হয় mg_ দিয়ে। শুধু-পাঠানো কী দিয়ে পাঠানো যায়, কিন্তু ইমেইল দেখা বা বাতিল করা যায় না; সেজন্য পূর্ণ অ্যাক্সেসের কী ব্যবহার করুন।
ইমেইল পাঠানো
POST /emails — একটি ইমেইল সর্বোচ্চ ৫০ জন প্রাপককে পাঠায় (to, cc ও bcc মিলিয়ে)।
| ফিল্ড | ধরন | বিবরণ |
|---|---|---|
from | string | প্রেরক, যেমন "Acme <[email protected]>"। ডোমেইনটি যাচাই করা থাকতে হবে। |
to | string | string[] | প্রাপকেরা। |
cc, bcc | string | string[] | ঐচ্ছিক কপি। |
reply_to | string | string[] | ঐচ্ছিক উত্তরের ঠিকানা। |
subject | string | বিষয়। |
html, text | string | মূল লেখা; অন্তত একটি। |
attachments | object[] | { filename, content (base64), content_type?, content_id? }; সব মিলিয়ে ২৫ MB পর্যন্ত। |
headers | object | বাড়তি হেডার, যেমন { "X-Entity-Ref-ID": "123" }। |
tags | object[] | { name, value } জোড়া, লগ ও ওয়েবহুকে দেখা যায়। |
scheduled_at | ISO 8601 | পরে পাঠান, ৩০ দিন পর্যন্ত। |
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" }]
}'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 -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 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 ব্যবহার করতে পারে।
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-এর সঙ্গে, এন্ডপয়েন্টের সিক্রেট দিয়ে।
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 | অনুরোধে কিছু ভুল আছে; বার্তায় তা বলা থাকে। |
401 | API কী নেই বা সঠিক নয়। |
403 | অনুমতি নেই: প্ল্যান নেই, ডোমেইন যাচাই হয়নি, কী দিয়ে এটি করা যায় না, বা পাঠানো বন্ধ। |
404 | ইমেইলটি পাওয়া যায়নি। |
413 | মেসেজটি অনেক বড়। |
429 | মিনিটে অনেক বেশি ইমেইল, ওয়ার্ম-আপ সীমা, বা এই মাসের পরিমাণ শেষ। |
5xx | আমাদের দিকে কিছু ভুল হয়েছে; আবার চেষ্টা করুন। |
- প্রতি ইমেইলে ৫০ জন প্রাপক, প্রতি ব্যাচে ১০০টি ইমেইল পর্যন্ত।
- সংযুক্তিসহ প্রতি ইমেইল ২৫ MB পর্যন্ত।
- ৩০ দিন পর্যন্ত আগে থেকে সময় ঠিক করা যায়।
- প্রতি মিনিটের হার ও মাসিক পরিমাণ আপনার প্ল্যানের ওপর নির্ভর করে।