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

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

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));