ارسال ایمیل با API
ارسال ایمیل با HTTP API بهجای SMTP — قالب پیام، جایگذاری متغیر و ارسال انبوه شخصیسازیشده روی زیرساخت AhaSend.
اگر به امکاناتی مثل جایگذاری متغیر در متن پیام، ارسال زمانبندیشده یا ارسال انبوهِ شخصیسازیشده نیاز دارید، بهجای SMTP از HTTP API استفاده کنید.
مثل 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 هم گزینهای است.