Документация по API

Мы предоставляем RESTFULL API для доступа к некоторым функциям нашего сервиса. Самое главное назначение данной функциональности - возможность добавления пописчика в листы нашего сервиса во время его регистрации на стороннем сайте. Вам не нужно скачивать или устанавливать какие-либо дополнительные библиотеки. Мы предоставляем набор методов, возвращающих данные в формате json, что является очень удобным кроссплатформенным решением, и позволит взаимодействовать с нашим сервисом посредствам любого поддерживающего данный формат языка программирования.

Для того, чтобы использовать api-функции Вы должны быть зарегистрированы на нашем сервисе и находиться на одном из коммерчеких тарифов. Для использования любой функции необходим секретный api-ключ, который Вы можете получить, оставив заявку в разделе тикетов личного кабинета.

С доступными методами, примерами кода и описаниями возвращаемых значений можете ознакомиться ниже.

Все параметры являются обязательными и должны быть переданы только через POST запрос.

Общие для всех методов возможные возвращаемые значения:

{"error":"api_key_not_found"} - секретный ключ не был передан в параметрах;

{"error":"invalid_api_key"} - передан неверный секретный ключ;

{"error":"deny_free_tarif"} - доступ с тарифа "Старт" запрещен;

{"error":"not_enough_money"} - баланс был исчерпан, пополните баланс в личном кабинете.

Вызов метода Описание Передаваемые параметры Возвращаемые значения
http://rumailer.ru/ru_api/get_quota Возвращает статистику по отправленным всего письмам, отправленным в этом месяце, о количестве подписчиков, о лимитах Вашего тарифа api_key - секретный ключ пользователя. {"result":{"count_send_letters":"2841", "max_letters_in_month":"300000", "send_letters_in_month":"1199", "max_tarif_subscribers":"10000", "count_subscribers":"1587"}} - всего отправлено писем; максимально возможно отправить за месяц; отправлено за текущий месяц; максимальное кол-во подписчиков на текущем тарифе
http://rumailer.ru/ru_api/get_lists Возвращает имя и id 100 последних листов api_key - секретный ключ пользователя. {"result":[{"title":"name_of_list1","id":"132108"},{"title":"name_of_list2","id":"129328"}, ... ]} - список листов с полями имени листа и его id
http://rumailer.ru/ru_api/get_balance Возвращает Ваш баланс в рублях api_key - секретный ключ пользователя. {"result":{"balance":"202.30"}} - баланас в рублях
http://rumailer.ru/ru_api/get_list_stat Возвращает статистику конкретного листа

api_key - секретный ключ пользователя;

list_id - id листа, статистику которого хотим получить.

{"result":{"count_all":"1", "count_unverified":"2", "count_disabled":"0", "count_unsubscribe":"0", "count_spam":"0", "need_update":"0"}} - count_all: общее кол-во подписчиков в листе; count_unverified: кол-во неактивированных подписчиков; count_disabled: кол-во неактивных подписчиков; count_unsubscribe: кол-во отписавшихся; count_spam: кол-во нажавших на спам; need_update: значение 1 - говорит о том, что статистика может быть неактуальной и необходимо перейти в данный лист в личном кабинете, чтобы актуализировать статистику, после этого значение станет равным 0
http://rumailer.ru/ru_api/add_subscriber Добавляет подписчика, используя различные опции, передаваемые в параметрах

api_key - секретный ключ пользователя;

list_ids - id значения листов, в которые хотим добавить подписчика через запятую без пробелов;

email - email подписчика, которого хотим добавить в листы;

fields - массив полей вида [ключ_параметра]=значение параметра. В качестве основных ключей используются firstname, lastname, middlename, city, address, phone, sex, birthday. Все остальные воспринимаются как дополнительные поля подписчика и не должны содержать кириллицу. Поле birthday обязательно должно иметь формат дд.мм.гггг;

double_optin - число от 0 до 3 - есть ли подтверждённое согласие подписчика, и что делать, если превышен лимит подписок.
Если 0, то мы считаем, что подписчик только высказал желание подписаться, но ещё не подтвердил подписку. В этом случае подписчику будет отправлено письмо-приглашение подписаться.
Если 1, то мы считаем, что у Вас уже есть согласие подписчика. Но при этом для защиты от злоупотреблений есть суточный лимит подписок. Если он не превышен, мы не посылаем письмо-приглашение. Если же он превышен, подписчику высылается письмо с просьбой подтвердить подписку. Лимиты мы согласовываем в индивидуальном порядке.
Если 2, то также считается, что у Вас согласие подписчика уже есть, но в случае превышения лимита мы возвращаем код ошибки too_many_double_optins.
Если 3, то также считается, что у Вас согласие подписчика уже есть, но в случае превышения лимита подписчик добавляется со статусом «новый».

{"error":"list_ids_not_found"} -не передан параметр идентификаторов листов;

{"error":"email_not_found"} -не передан параметр email-адреса добавляемого подписчика;

{"error":"bad_email"} - передан некорректный параметр email-адреса добавляемого подписчика;

{"error":"list_ids_not_found"} - идентификаторы листов неверного формата (верный формат через запятую без пробелов);

{"error":"detected_alien_list"} - переданный идентификатор листа принадлежит чужому аккаунту;

{"error":"limit_of_count_subscribers_is_exceeded"} - Вы исчерпали лимит кол-ва добавляемых подписчиков своего тарифа. Требуется перейти на тариф с большим кол-вом подписчиков;

{"error":"email_is_disabled"} - email адрес добавляемого подписчика уже был отписан от рассылок, либо неактивен;

{"result":{"already_in_lists":["1298","1277","1271"]}} - отдает id листов, в которых данный email уже присутствует, причем алгоритм добавления на этом не обрывается, а доходит до конца, скорее всего это поле дополнится еще одним со статусом выполнения операции;

{"result":{"status":"ok"}} - возвращается, когда в одном из Ваших листов уже есть активный подписчик с таким email адресом, при этом во всех остальных листах подписчики с такими адресами становятся активными, а в листах, где их не было, но куда их необходимо добавить, они вставятся уже верифицированными;

{"result":{"status":"send_ver_letter"}} - оповещает о том, что было отправлено письмо верификации;

{"result":{"status":"already_send_verification"}} - оповещает о том, что письмо верификации для данного email адреса было отправлено ранее и отправить его сейчас нельзя. Необходимо дождаться реакции пользователя на предыдущее письмо;

{"result":{"status":"added"}} - оповещает о том, что подписчик был успешно добавлен в лист, кол-во доверительных верификаций при этом уменьшилось на 1;

{"error":"too_many_double_optins"} - ошибка, возникающая при передаче параметра double_optin=2. Кол-во доверительных верификаций было исчерпано;

 

Возвращаемые значения объекта result могут содержать несколько полей, например, {"result":{"already_in_lists":["1298","1277"], "status":"added"}}.

Примеры использования на php:


	//Убедитесь, что модуль curl включен
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'http://rumailer.ru/ru_api/add_subscriber');
	curl_setopt($ch, CURLOPT_POST, 1);
        //массив полей может передаваться как в сериализованном виде, так и в виде массива
        //т.к.мы преобразуем его здесь через urlencode, то необходимо, чтобы он передавался в виде строки
	$fields=serialize(array('firstname'=>'Иван','lastname'=>'Иванов'));
	$data = 'list_ids='.urlencode('12,13,14').
		'&api_key='.urlencode('xxxxxxxxxxxxxxxxxxxxxxx').
		'&email='.urlencode('test@test.ru').
		'&double_optin=1
		&fields='.urlencode($fields);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
	$header = "Content-Type: application/x-www-form-urlencodedrn";
	$header .= "Content-Length: ".strlen($data)."rnrn";
	curl_setopt($ch, CURLOPT_HEADER, $header);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	$result = curl_exec($ch);
	curl_close($ch);
	//переменная $result вернет какой-то из описанных в таблице вариантов
	print_r($result);
	//то, что может вернуться в $result
	/*{
		"result":{
			"already_in_lists":["12","13","14"],
			"status":"ok"
		}
	}*/	

	//преобразуем json в php переменную и распоряжаемся ей на своё усмотрение
	$result=json_decode($result);
	print_r($result);
	/*stdClass Object
	(
		[result] => stdClass Object
			(
				[already_in_lists] => Array
					(
						[0] => 12
						[1] => 13
						[2] => 14
					)

				[status] => ok
			)

	)*/	
	


Подождите...