رفتن به محتوای اصلی

ارسال ایمیل با API

ارسال ایمیل با HTTP API به‌جای SMTP — قالب پیام، جایگذاری متغیر و ارسال انبوه شخصی‌سازی‌شده روی زیرساخت AhaSend.


اگر به امکاناتی مثل جایگذاری متغیر در متن پیام، ارسال زمان‌بندی‌شده یا ارسال انبوهِ شخصی‌سازی‌شده نیاز دارید، به‌جای SMTP از HTTP API استفاده کنید.

این هم روی AhaSend است

مثل SMTP، این API هم متعلق به AhaSend است و با API Key حساب AhaSend کار می‌کند — نه کلید API نجوا. فعلاً امکان ساخت مستقیم حساب یا کلید در AhaSend برای مشتریان نجوا وجود ندارد؛ برای فعال‌سازی و دریافت API Key با پشتیبانی نجوا تماس بگیرید.

احراز هویت

هر درخواست به دو چیز نیاز دارد: شناسهٔ حساب (account_id) در مسیر URL، و کلید API در هدر:

Authorization: Bearer YOUR_API_KEY

ارسال یک ایمیل ساده

curl --request POST \
--url "https://api.ahasend.com/v2/accounts/{account_id}/messages" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"from": { "email": "no-reply@yourdomain.com", "name": "کسب‌وکار شما" },
"recipients": [
{ "email": "user@example.com", "name": "کاربر نمونه" }
],
"subject": "خوش‌آمدید",
"text_content": "سلام! از ثبت‌نام شما خوشحالیم."
}'

فیلدهای بدنهٔ درخواست

فیلداجباریتوضیح
from.email / from.nameبلهآدرس و نام نمایشی فرستنده
recipientsبلهآرایه‌ای از {email, name}
subjectبلهموضوع ایمیل
text_contentیکی از این دو الزامینسخهٔ متنی ساده
html_contentیکی از این دو الزامینسخهٔ HTML
substitutionsخیرمقداردهی متغیرهایی مثل {{name}} در متن پیام
چند گیرنده یعنی چند ایمیل جدا

وقتی چند آیتم در recipients می‌گذارید، یک ایمیل با چند گیرنده در فیلد To نمی‌رود — برای هرکدام یک ایمیل جدا و شخصی‌سازی‌شده ساخته می‌شود. هر گیرنده فقط آدرس خودش را می‌بیند و می‌تواند مقدار substitutions جداگانه‌ای داشته باشد.

ارسال با جایگذاری متغیر

{
"from": { "email": "newsletter@yourdomain.com", "name": "خبرنامهٔ شما" },
"recipients": [
{ "email": "user1@example.com", "name": "کاربر یک" },
{ "email": "user2@example.com", "name": "کاربر دو" }
],
"subject": "خبرنامهٔ {{month}}",
"html_content": "<h1>خبرنامهٔ {{month}}</h1><p>{{name}} عزیز، این ماه چه خبر...</p>",
"substitutions": {
"month": "مهر",
"name": "کاربر گرامی"
}
}

پاسخ موفق

{
"object": "list",
"data": [
{
"object": "message",
"id": "3f8e2b1a-7c4d-4e2a-9b1e-2f3a4b5c6d7e",
"recipient": { "email": "user@example.com", "name": "کاربر نمونه" },
"status": "queued",
"error": null,
"schedule": {
"first_attempt": "2026-09-20T10:30:00Z",
"expires": "2026-09-21T10:30:00Z"
}
}
]
}

چون هر گیرنده ایمیل جدای خودش را دارد، data یک آرایه است — یک آیتم به ازای هر گیرنده، با id و status مستقل.

کدهای خطای HTTP

کدمعنی
400بدنهٔ درخواست ناقص یا نامعتبر است
401کلید API غایب یا نامعتبر است
403کلید API معتبر است ولی به این عملیات/حساب دسترسی ندارد
409تداخل در درخواست (مثلاً استفادهٔ تکراری از یک کلید idempotency)
جزئیات کامل

برای معنای دقیق هر خطا در حالت‌های خاص (دامنهٔ تأییدنشده، محدودیت پلن و…) به مستندات API نجوا در سایت AhaSend مراجعه کنید.

حالت آزمایشی (Sandbox)

پیش از اتصال واقعی، AhaSend یک حالت Sandbox دارد که درخواست را می‌پذیرد ولی ایمیل واقعی ارسال نمی‌کند — برای تست ساختار درخواست‌ها در محیط توسعه مناسب است.

گام بعدی

برای ارسال‌های ساده‌تر بدون نیاز به قالب یا زمان‌بندی، ارسال با SMTP هم گزینه‌ای است.