وب‌سرویس ایمیل

آدرس وب‌سرویس

آدرس وب‌سرویس ایمیل به صورت زیر است:

echo 'http://webservice1.link/ws/v1/rest/email/{method}.json;

 

که به جای عبارت {method} نام متد مورد نظر قرار می‌گیرد.

پینگ سرور

توضیح عملکرد متد

با فراخوانی این متد، یک پاسخ ساده از سرور ایمیل بازگشت داده می‌شود تا بتوان از درستی اتصال بین برنامه و سرور ایمیل اطمینان حاصل کرد. نحوه فراخوانی این متد به صورت زیر است:

آدرس متدهای مجاز
http://webservice1.link/ws/v1/rest/email/ping.json GET

پارامترهای ورودی

این متد هیچ پارامتری ندارد.

نتیجه خروجی

نام نوع داده ثابت | احتمالی توضیحات
string  ثابت متن ثابت وضعیت سرور

متن بازگشتی برابر رشته‌ی I'm up است که نشان می‌دهد سرور مشکلی ندارد.

نمونه پاسخ JSON

{"code":0,"message":"","result":{"response":"I'm up!"}}

نمونه کد PHP

$baseUrl = 'http://webservice1.link/ws/v1/rest/'
$serviceUrl = $baseUrl . 'email/ping.json';
$curl = curl_init($serviceUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curlResponse = curl_exec($curl);
curl_close($curl);
print_r(json_decode($curlResponse, true));

لیست خطاها

هر پاسخی جز نتیجه خروجی بالا، میتواند نشان از بروز خطا در سرور ایمیل باشد.

ارسال ایمیل

توضیح عملکرد متد

برای ارسال ایمیل به گیرندگان مورد نظر استفاده می‌شود. برای ارسال، بایستی درخواست خود را به صورت زیر ارسال نمایید:

آدرس متدهای مجاز
http://webservice1.link/ws/v1/rest/email/send.json POST

پارامترهای ورودی

پارامترهای مورد نیاز ارسال به صورت زیر است:

نام نوع داده اجباری | اختیاری توضیحات
api string اجباری شناسه رمز ایمیل
data array اجباری اطلاعات ارسال
  • api: شناسه رمز ایمیل (api key) که داخل پنل کاربری شما قرار دارد.
  • data: آرایه‌ای از داده‌های مورد نیاز برای ارسال ایمیل که خود شامل موارد زیر است:
نام نوع داده اجباری | اختیاری توضیحات
sender_name string اجباری نام فرستنده ایمیل
subject string اجباری موضوع ایمیل
content string اجباری متن ایمیل (شامل کد HTML)
recipients string | array اجباری آدرس ایمیل گیرندگان
  • sender_name: نام فرستنده ایمیل ارسالی است که در ایمیل ارسالی دیده می‌شود.
  • subject: موضوع ایمیل ارسالی است که در بخش subject ایمیل ارسالی دیده می‌شود.
  • content: محتوای ایمیل ارسالی است که میتواند شامل کد HTML باشد.
  • recipients: لیستی از آدرس‌های گیرندگان است که در حال حاضر به ۲ صورت میتواند تعیین گردد:
    1. رشته‌ای (string) شامل لیست آدرس‌های ایمیل گیرندگان که با علامت , از یکدیگر جدا شده اند.
    2. آرایه‌ای از آدرس‌های ایمیل گیرندگان.

نتیجه خروجی

نام نوع داده ثابت | احتمالی توضیحات
id integer  ثابت شناسه درخواست ارسال ایمیل
  • id: شناسه درخواست ایمیل که برای گزارش‌گیری و موارد مربوط به آن می‌تواند مورد استفاده قرار گیرد.

نمونه پاسخ JSON

{
  "code":0,
  "message":"",
  "result":{
    "id":11327
  }
}

نمونه کد PHP

$baseUrl = 'http://webservice1.link/ws/rest/';
$serviceUrl = $baseUrl . 'email/send.json';
$api = 'شناسه رمز ایمیل شما';
$curl = curl_init($serviceUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
$data = array(
    'api' => $api,
    'data' => array(
        'sender_name' => 'نام ارسال کننده',
        'subject' => 'موضوع ایمیل شما',
        'content' => '<h2>متن ایمیل شما</h2>',
        'recipients' => 'test@example.com, test2@example.com'
    )
);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($data));
$curlResponse = curl_exec($curl);
curl_close($curl);
print_r(json_decode($curlResponse, true));

گزارشات ارسال

توضیح عملکرد متد

برای دریافت لیست درخواست‌های ارسال ایمیل استفاده می‌شود. نحوه ارسال درخواست به صورت زیر است:

آدرس متدهای مجاز
http://webservice1.link/ws/v1/rest/email/logs.json POST | GET

پارامترهای ورودی

پارامتر‌های مورد نیاز به صورت زیر است:

نام نوع داده اجباری | اختیاری توضیحات
api string اجباری شناسه رمز ایمیل
options array اختیاری تنظیمات
  • api: شناسه رمز ایمیل (api key) که داخل پنل کاربری شما قرار دارد.
  • options: آرایه‌ای از تنظیمات و اطلاعات درخواست که شامل موارد زیر است:
نام نوع داده اجباری | اختیاری توضیحات
page integer اختیاری شماره صفحه
count integer اختیاری تعداد در هر صفحه
  • page: شماره صفحه مورد نظر که میتواند برای صفحه‌بندی در برنامه استفاده گردد. با افزایش این مقدار، میتوان به درخواست‌های قدیمی‌تر دسترسی داشت.
  • count: تعداد نتایج و درخواست‌های بازگشتی در هر صفحه است. با افزایش این مقدار، میتوان به درخواست‌های بیشتری دسترسی داشت.

نتیجه خروجی

نام نوع داده ثابت | احتمالی توضیحات
count integer  ثابت تعداد کل درخواست‌ها
emails array ثابت لیست درخواست‌های ایمیل
  • count: تعداد کل درخواست‌های ایمیل.
  • emails: آرایه‌ای از درخواست‌های ایمیل که شامل اشیایی (object) است که هر کدام از آن‌ها دارای ویژگی‌های زیر است:
نام نوع داده ثابت | احتمالی توضیحات
id integer  ثابت شناسه درخواست ارسال ایمیل
sender_name string ثابت نام ارسال‌کننده
sender_email string ثابت آدرس ایمیل ارسال کننده
subject string ثابت موضوع ایمیل
recipients_count integer ثابت تعداد گیرندگان ایمیل
type integer ثابت نوع درخواست ایمیل
price integer ثابت هزینه کل درخواست
send_time string ثابت زمان ارسال ایمیل‌
status integer ثابت وضعیت درخواست
created_at string ثابت زمان ثبت درخواست
link string ثابت آدرس اینترنتی محتوای ایمیل

نمونه پاسخ JSON

{
  "code": 0,
  "message": "",
  "result": {
    "count": 177,
    "emails": [
      {
        "id": 11330,
        "sender_name": "نام ارسال کننده",
        "sender_email": "info@bazarhadaf.com",
        "subject": "موضوع ایمیل شما",
        "recipients_count": 2,
        "type": 1,
        "price": 20,
        "send_time": "2015-05-23 12:32:53",
        "status": 2,
        "created_at": "2015-05-23 12:32:53",
        "link": "http://server206.com/email/f7e71aae4609678fc3143fffad65c880"
      }
    ]
  }
}

نمونه کد PHP

$baseUrl = 'http://webservice1.link/ws/rest/';
$serviceUrl = $baseUrl . 'email/logs.json';
$api = 'شناسه رمز ایمیل شما';
$curl = curl_init($serviceUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
$data = array(
    'api' => $api,
    'options' => array(
        'page' => 2,
        'count' => 5
    )
);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($data));
$curlResponse = curl_exec($curl);
curl_close($curl);
print_r(json_decode($curlResponse, true));

دریافت اطلاعات کاربری

توضیح عملکرد متد

برای دریافت اطلاعات کاربری استفاده می‌شود. اطلاعات بازگشتی شامل هزینه‌ها، محدودیت‌ها و لیست آی‌پی‌های ثبت شده برای کاربر می‌باشد. نحوه ارسال درخواست به صورت زیر می‌باشد:

آدرس متدهای مجاز
http://webservice1.link/ws/v1/rest/email/info.json GET

پارامترهای ورودی

پارامتر‌های مورد نیاز به صورت زیر است:

نام نوع داده اجباری | اختیاری توضیحات
api string اجباری شناسه رمز ایمیل
  • api: شناسه رمز ایمیل (api key) که داخل پنل کاربری شما قرار دارد.

نتیجه خروجی

نام نوع داده ثابت | احتمالی توضیحات
normal_price integer  ثابت هزینه ارسال عادی
 ad_price integer ثابت هزینه ارسال تبلیغاتی
 minimum_count integer ثابت حداقل تعداد گیرندگان
maximum_count  integer  ثابت  حداکثر تعداد گیرندگان
 ip_list string ثابت لیست آی‌پی‌های مجاز
  • normal_price: هزینه ارسال عادی ایمیل به ازای هر گیرنده که واحد آن ریال می‌باشد.
  • ad_price: هزینه ارسال تبلیغاتی ایمیل به ازای هر گیرنده که واحد آن ریال می‌باشد. این نوع ارسال با استفاده از گروه‌های تبلیغاتی ما انجام میپذیرد.
  • minimum_count: حداقل تعداد گیرندگان ایمیل به ازای هر درخواست ارسال. در صورت نیاز به تغییر این مقدار، می‌توانید درخواست خود را به پشتیبانی فروتل اعلام نمایید.
  • maximum_count: حداکثر تعداد گیرندگان ایمیل به ازای هر درخواست ارسال. در صورت نیاز به تغییر این مقدار، می‌توانید درخواست خود را به پشتیبانی فروتل اعلام نمایید.
  • ip_list: لیست آدرس‌های ip های مجاز شما برای ارسال درخواست به وب‌سرویس ایمیل که با علامت , (کاما) از یکدیگر جدا شده‌اند. در صورت نیاز به تغییر این مقدار، می‌توانید درخواست خود را به پشتیبانی فروتل اعلام نمایید.

نمونه پاسخ JSON

{
  "code": 0,
  "message": "",
  "result": {
    "normal_price": 10,
    "ad_price": 350,
    "minimum_count": 2,
    "maximum_count": 10000,
    "ip_list": "192.168.1.1,192.168.1.2"
  }
}

نمونه کد PHP

$baseUrl = 'http://webservice1.link/ws/rest/';
$serviceUrl = $baseUrl . 'email/info.json';
$api = 'شناسه رمز ایمیل شما';
$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$data = array(
    'api' => $api
);
curl_setopt($curl, CURLOPT_URL, $serviceUrl . '?' . http_build_query($data));
$curlResponse = curl_exec($curl);
curl_close($curl);
print_r(json_decode($curlResponse, true));

دریافت شارژ حساب

توضیح عملکرد متد

برای دریافت مقدار فعلی شارژ حساب کاربری استفاده می‌شود. نحوه ارسال درخواست به صورت زیر است:

آدرس متدهای مجاز
http://webservice1.link/ws/v1/rest/email/charge.json GET

پارامترهای ورودی

پارامتر‌های مورد نیاز به صورت زیر است:

نام نوع داده اجباری | اختیاری توضیحات
api string اجباری شناسه رمز ایمیل
  • api: شناسه رمز ایمیل (api key) که داخل پنل کاربری شما قرار دارد.

نتیجه خروجی

{
  "code": 0,
  "message": "",
  "result": 9599970
}

نمونه کد PHP

$baseUrl = 'http://webservice1.link/ws/rest/';
$serviceUrl = $baseUrl . 'email/charge.json';
$api = 'شناسه رمز ایمیل شما';
$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$data = array(
    'api' => $api
);
curl_setopt($curl, CURLOPT_URL, $serviceUrl . '?' . http_build_query($data));
$curlResponse = curl_exec($curl);
curl_close($curl);
print_r(json_decode($curlResponse, true));