NewsMAN API: subscriber.initSubscribe

Sections

Newsman – Knowledge Base

HomeAPISubscribersubscriber.initSubscribe

Newsman Api Method: subscriber.initSubscribe

Prototype: subscriber.initSubscribe(list_id, email, firstname, lastname, ip, props, options)

Description: Inits a confirmed opt in subscribe. Email is sent first to the subscriber with an unique link which has to be clicked.

HTTP method: POST

Endpoint HTTP: /subscriber.initSubscribe.json

Endpoint XML-RPC: subscriber.initSubscribe

Return type: string|int

Return info: The action id

Request parameters POST

Variable	Type	Description
list_id	string\|int	The ID of the list in which to save the subscription
email	string	The email of the subscriber
firstname	string\|null	The firstname of the subscriber, can be null.
lastname	string\|null	The lastname of the subscriber, can be null.
ip	string	The ip address of the subscriber
props	struct\|null	Hash array with props (can be later used to build segment criteria)
options	struct\|null	Hash array with options for this init subscribe. Valid keys are: segments: array with segment ids where user will be added template_id: string with the ID of the template used for sending out the confirmation email. Templates are created through the template API. form_id: string with the ID of the form used for confirmation email and form settings. Forms are created in the admin. check_already_subscribed: Check if the subscriber is already subscribed in the list.

Response parameters

Parameter	Description
int	The action id

curl "https://ssl.newsman.app/api/1.2/rest/your_user_id/your_api_key/subscriber.initSubscribe.json?list_id=my_list_id&email=test%40example.com&firstname=null&lastname=null&ip=the_ip_address&props[some_prop]=some_value&options[segments][]=15002"

// https://github.com/Newsman/newsman-api-php

<?php
 
require_once("Newsman/Client.php");
 
// you can get your API KEY, your newsman_user_id and list_id from My account -> API
$newsman_user_id = "your-user-id";
$api_key = "your-api-key";
$list_id = "my_list_id"; // The ID of the list
$email = "test@example.com"; // the email
$firstname = null; // the firstname
$lastname = null; // the lastname
$ip = "the_ip_address"; // the ip
$props = array("some_prop" => "some_value"); // props
$options = array("segments" => array(15002)); // options
 
try {
	$client = new Newsman_Client($newsman_user_id, $api_key);
	$ret = $client->subscriber->initSubscribe($list_id, $email, $firstname, $lastname, $ip, $props, $options);
} catch (Exception $e) {
	//do something with the error, eg: log $e->getMessage()
}
 
return $ret;
 
?>

# https://github.com/Newsman/newsman-api-python

import newsman
 
user_id = "your_user_id"
api_key = "your_api_key"
list_id = "my_list_id"
subscriber_email = "test@example.com"
firstname = null
lastname = null
ip = "the_ip_address"
 
props =	{
  "some_prop": "some_value"  
}
 
options = {
  "segments": [15002]
}
 
client = newsman.Newsman(user_id, api_key)
client.subscriber.initSubscribe(list_id, subscriber_email, firstname, lastname, ip, props, options)

// https://github.com/Newsman/newsman-api-dotnet

RESTClient client = new RESTClient("your_user_id", "your_api_key");
 
var _props = new NameValueCollection();
    _props["some_prop"] = "some_value";
 
int[] _segments = new int[]  { 15002 };    
var _options = new NameValueCollection();
    _options["segments"] = _segments;    
 
var _params = new NameValueCollection();
    _params["list_id"] = "my_list_id";
    _params["email"] = "test@example.com";
    _params["firstname"] = null;
    _params["lastname"] = null;
    _params["ip"] = "the_ip_address";
    _params["props"] = _props;
    _params["options"] = _options;
 
var response = client.CallMethod("subscriber", "initSubscribe", _params);

Output example

Response Errors

Code	Message	Description
407	Missing required param list_id	list_id param is required
407	Missing required param email	email param is required
407	Missing required param firstname	firstname param is required
407	Missing required param lastname	lastname param is required
407	Missing required param ip	ip param is required
407	Missing required param props	props param is required
407	Missing required param options	options param is required
101	Not allowed for list_id = %s	Invalid access to subscriber list_id
108	List %s has been deleted	List ID belongs to a list which has been deleted
122	Invalid IP received $ip	The IP is invalid
126	Optout email received %s	Optout email. Only initsubscribe is allowed.
123	Invalid email address %s.	The email is not valid
10001	Cannot use both template_id and form_id	Cannot use both template_id and form_id in options
128	Too many requests for this subscriber. Can only send once per 10 minutes	Can only send once per 10 minutes to the same email
144	Cannot subscribe to this segment	Cannot subscribe to this segment
201	Internal Error: %s	A database error occurred

Error examples

{
    "err": true,
    "message": "Missing required param list_id",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param email",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param firstname",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param lastname",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param ip",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param props",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param options",
    "code": 407
}

{
    "err": true,
    "message": "Invalid IP received 127.0.0.1",
    "code": 122
}

{
    "err": true,
    "message": "Too many requests for this subscriber. Can only send once per 10 minutes",
    "code": 128
}

{
    "err": true,
    "message": "Subscriber is already subscribed",
    "code": 130
}