Create a new Subscriber


×
For API key Please contact with us at our SMTPprovider web chat

URL

POST https://spsrvr.com/ga/api/v2/mailing_lists/:mailing_list_id/subscribers

Request Parameters

Key Meaning Example
mailing_list_id The mailing list to onto which to add the subscriber 99182

Request Payload

The POST request should have a JSON document in its payload with all of the following keys.

Key Meaning Example Type
subscriber.email The subscriber’s email address bob@example.com String
subscriber.confirmed The subscriber’s confirmed status. This column is only needed for mailing lists which use the Confirmed field. true or false Boolean
subscriber.email_format The subscriber’s email format. This column is only needed for mailing lists which use the Format field. plaintext or html String
subscriber.status The status of the subscriber. active, bounced, unsubscribed, scomp or deactivated String
subscriber.subscribe_time The time the subscriber subscribed. 2013-03-27T10:14:13-05:00 String
subscriber.subscribe_ip The IP the subscriber subscribed from. This can be null if it is unknown. 192.168.0.123 String
subscriber.custom_fields An array of entries matching the definition found below (1). Hash
subscriber.skip_autoresponders Do not run autoresponders for this new subscriber (see 2.1 below). false Boolean
subscriber.autoresponder_filter Only run the autoresponders that match this case-insensitive string glob (see 2.4 below). Subscription Autoresponder Sequence* String
subscriber.autoresponder_exclude_reacted Do not run autoresponders if this subscriber has a reaction in the queue (see 2.5 below). true Boolean

(1) Each entry in the specified custom_fields hash must have the following keys. The keys for the hash is the name of the custom field.

Key Meaning Example Type Present for Custom Field Types
name The name of the custom field which this entry represents. First Name String All
value The string value of the custom field. James McGuy String text, text_multiline, select_single_dropdown, select_single_radio
value The integer value of the custom field. 9182 Integer number
value The boolean value of the custom field. true or false Boolean boolean
value The date value of the custom field. 2000-02-17 String date
value The list of values selected for the custom field. Array of strings select_multiple_checkboxes

(2) In order for an autoresponder to be triggered for later sending, the following must be true.

  1. The skip_autoresponders field must not be enabled.
  2. The autoresponder must trigger on Subscription.
  3. The autoresponder trigger must be configured with the Run From API? option enabled.
  4. If specified, the autoresponder_filter field will reduce the list of autoresponders that are run to those whose name matches the glob, where * is a wildcard character.
  5. If specified, the autoresponder_exclude_reacted field will cause all autoresponders to be skipped if any autoresponder remaining at this point contains a reaction in the queue for this subscriber. This only evaluates autoresponders that: (a) are configured with Run from API? as true (step 3), (b) match the pattern provided in autoresponder_filter if present (step 4), and (c) are paused or un-paused.

Response

A successful response will return the subscriber record using the format described in the “Get subscriber details” section of the API.

A failure will return a standard error response with an explanation of what went wrong.

Example

> POST /ga/api/v2/mailing_lists/4/subscribers HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1hgjgkjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: Smtpprovider-studio.dev
> Accept: */*
> Content-Length: 430
> Content-Type: application/json
{
    "subscriber": {
        "custom_fields": {
            "First Name": "Ted",
            "boolean test": false,
            "boolean test yes by default": true,
            "radio test": "bar"
        },
        "email": "ted@example.com",
        "mailing_list_id": 4,
        "status": "active",
        "subscribe_ip": null,
        "subscribe_time": "2013-02-01T08:22:42-06:00"
    }
}
< HTTP/1.1 200 OK
< Content-Type: text/html
< X-UA-Compatible: IE=Edge
< ETag: "e5794f737673a63d76a5741a66332d22"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=d27440cb5fba4c7a579920acd8986636; path=/; HttpOnly
< X-Request-Id: 293ca6db3ed520f5be284686cfc7b7ed
< X-Runtime: 0.046717
< Connection: close
{
    "data": {
        "created_at": "2013-03-29T13:27:50-05:00",
        "custom_fields": {
            "First Name": {
                "name": "First Name",
                "type": "text",
                "value": "Ted"
            },
            "boolean test": {
                "name": "boolean test",
                "type": "boolean",
                "value": false
            },
            "boolean test yes by default": {
                "name": "boolean test yes by default",
                "type": "boolean",
                "value": true
            },
            "radio test": {
                "name": "radio test",
                "type": "select_single_radio",
                "value": "bar"
            }
        },
        "email": "ted@example.com",
        "id": 3386566,
        "mailing_list_id": 4,
        "status": "active",
        "subscribe_ip": null,
        "subscribe_time": "2013-02-01T08:22:42-06:00"
    },
    "error_code": null,
    "error_message": null,
    "success": true
}

PHP Example :

<?php

// API Configuration
$api_key = 'API_KEY_HERE_FROM_WEB_UI';
$api_url = 'http://spsrvr.com/ga/api';
 
// Subscriber data
$listID = 5;
$email = 'customer1@example.com';

 
// subscriberAdd.php - Example 
// API's subscriberAdd method.
 
// API request.
$request = array(
    'email'  => $email,
    'confirmed' => true,
    'email_format' => 'html',
    'status' => 'active',
    'subscribe_time' => date('c'),
    'subscribe_ip' => null,
);
 
$request_url = "$api_url/mailing_lists/$listID/subscribers";
 
print "\nRequesting\n$request_url\n";
 
$request_handle = curl_init($request_url);
curl_setopt($request_handle, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($request_handle, CURLOPT_USERPWD, "$api_key");
curl_setopt($request_handle, CURLOPT_POST, true);
curl_setopt($request_handle, CURLOPT_POSTFIELDS, json_encode($request));
curl_setopt($request_handle, CURLOPT_RETURNTRANSFER, true);
$request_result = curl_exec($request_handle);
 
print "\nThe results are:\n";
print_r(json_decode($request_result));