Subscribers

API change history

With the Yesmail Subscribers API, a client can interact with Yesmail’s core systems in order to perform subscriber management activities.

A subscriber is considered to be anyone who belongs to or opts-in to a service or e-commerce firm and knowingly receives email messages from the service or company. It can also be someone who has unsubscribed from all messages.

A subscriber is specified via a company-defined identifier (ID). This identifier can be any string that is uniquely associated with a subscriber within a particular business unit in your organization. The ID will be tied in Yesmail’s systems to the subscriber’s profile information (including attributes), subscriptions, and message history for that business unit.

Note that if an ID is used across business units, it is stored separately for each business unit. The profile information, subscriptions, and message history for that ID are not joined across business units.

A subscription (or division) represents the level of organization at which the subscriber may opt-in, or subscribe. For instance, your company may have five different product areas; a subscriber may be opted in to one or more of these areas, while not subscribed to the others. Depending on the API call, the response payload may contain a memberOf array listing the divisions to which the subscriber is subscribed, and/or a current array that lists all available divisions and the subscriber's current status for each one.

A subscriber that is marked dead due to exceeding the hard bounce rules, is not editable. However, they can be revived through any of the subscriber update resources by setting dead=false.

Please note that all subscriber call email addresses must be lower-case strings. Calls containing email addresses in mixed case will be rejected.

/

Auto generated using Swagger Inspector

Try it

Request

Request URL

Request parameters

  • (optional)
    string
  • (optional)
    integer

    Valid values are integers 0-100.

  • (optional)
    integer

    Valid values are 0-any positive integer.

Request headers

  • string
  • string
    Subscription key which provides access to this API. Found in your Profile.

Request body

Responses

200 OK

Auto generated using Swagger Inspector

Representations

{
  "view": "string",
  "total": 0,
  "offset": 0,
  "subscribers": [
    {
      "dateCreated": "string",
      "lastUpdate": "string",
      "id": "string",
      "email": "string"
    }
  ],
  "limit": 0,
  "count": 0
}
{
  "type": "object",
  "properties": {
    "view": {
      "type": "string"
    },
    "total": {
      "type": "integer",
      "format": "int32"
    },
    "offset": {
      "type": "integer",
      "format": "int32"
    },
    "subscribers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dateCreated": {
            "type": "string"
          },
          "lastUpdate": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    },
    "limit": {
      "type": "integer",
      "format": "int32"
    },
    "count": {
      "type": "integer",
      "format": "int32"
    }
  }
}

Code samples

@ECHO OFF

curl -v -X GET "https://api.test.yesmail.com/v2/subscribers/?view={string}&limit=25&offset=0"
-H "Api-User: "
-H "api-key: {subscription key}"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Api-User", "");
            client.DefaultRequestHeaders.Add("api-key", "{subscription key}");

            // Request parameters
            queryString["view"] = "{string}";
            queryString["limit"] = "25";
            queryString["offset"] = "0";
            var uri = "https://api.test.yesmail.com/v2/subscribers/?" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://api.test.yesmail.com/v2/subscribers/");

            builder.setParameter("view", "{string}");
            builder.setParameter("limit", "25");
            builder.setParameter("offset", "0");

            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);
            request.setHeader("Api-User", "");
            request.setHeader("api-key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "view": "{string}",
            "limit": "25",
            "offset": "0",
        };
      
        $.ajax({
            url: "https://api.test.yesmail.com/v2/subscribers/?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Api-User","");
                xhrObj.setRequestHeader("api-key","{subscription key}");
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://api.test.yesmail.com/v2/subscribers/";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"view={string}",
                         @"limit=25",
                         @"offset=0",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    [_request setValue:@"" forHTTPHeaderField:@"Api-User"];
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"api-key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://api.test.yesmail.com/v2/subscribers/');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Api-User' => '',
    'api-key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'view' => '{string}',
    'limit' => '25',
    'offset' => '0',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Api-User': '',
    'api-key': '{subscription key}',
}

params = urllib.urlencode({
    # Request parameters
    'view': '{string}',
    'limit': '25',
    'offset': '0',
})

try:
    conn = httplib.HTTPSConnection('api.test.yesmail.com')
    conn.request("GET", "/v2/subscribers/?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Api-User': '',
    'api-key': '{subscription key}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'view': '{string}',
    'limit': '25',
    'offset': '0',
})

try:
    conn = http.client.HTTPSConnection('api.test.yesmail.com')
    conn.request("GET", "/v2/subscribers/?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://api.test.yesmail.com/v2/subscribers/')

query = URI.encode_www_form({
    # Request parameters
    'view' => '{string}',
    'limit' => '25',
    'offset' => '0'
})
if query.length > 0
  if uri.query && uri.query.length > 0
    uri.query += '&' + query
  else
    uri.query = query
  end
end

request = Net::HTTP::Get.new(uri.request_uri)
# Request headers
request['Api-User'] = ''
# Request headers
request['api-key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body