آدرس وبسرویس
آدرس وبسرویس ایمیل به صورت زیر است:
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: لیستی از آدرسهای گیرندگان است که در حال حاضر به ۲ صورت میتواند تعیین گردد:
- رشتهای (string) شامل لیست آدرسهای ایمیل گیرندگان که با علامت , از یکدیگر جدا شده اند.
- آرایهای از آدرسهای ایمیل گیرندگان.
نتیجه خروجی
نام |
نوع داده |
ثابت | احتمالی |
توضیحات |
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));