API Reference (Marketing API)

SocketLabs On-Demand Marketing API Guide


Marketing API Overview

API Purpose

The SocketLabs On-Demand Marketing API exposes RESTful HTTP methods to access and manipulate aspects of SocketLabs’ Marketing features such as contact list management, newsletters, and autoresponders. This enables users to build their own sophisticated client tools to manage the use of our On-Demand services. [▲]

Access & Authentication

The email Marketing API uses basic authentication over SSL. Please refer to your development platform documentation for instructions on how to use HTTP authentication with REST calls. All calls to the API must be over HTTPS for security. Non-secure HTTP calls are not supported.

Email marketing API credentials exist on a per-server level. Therefore, your Marketing API username is your 4- or 5-digit Server ID number, and a Marketing API key is used as a password. In order to retrieve your Marketing API key, log into your control panel and navigate to your server’s dashboard. From here, click on the “For Developers” tab in the top navigation bar, and choose the “Configure Marketing API” option in the drop-down menu. Your Marketing API key is automatically generated and cannot be edited manually for security reasons. You can regenerate this key, however, by clicking on the regenerate icon to the right of the field.

Please be aware that if you change any of your email marketing API credentials, any application that uses old information will stop working until it is updated with the new credentials. Any requests with invalid credentials will receive a 401 Unauthorized response. [▲]

Using the Marketing API

Best Practices

The email Marketing API currently exposes methods for managing contacts, contact lists, custom fields and custom field data.

JSON and XML response content types are currently supported. You can specify your preferred type via your Accept header in your HTTP request as follows (Accept: application/json or Accept: text/xml respectively).

For a given server, note that a contact is uniquely identified by its email address and contacts are shared across lists. Therefore if you update an individual contact’s information (first name, last name, etc) those changes will be reflected across all lists (and subsequent newsletters or autoresponders) on which that contact is used. [▲]

Error Handling

Your application should be designed to handle failure conditions such as receiving no response or an error response from our API server. For example, the email marketing API may be down temporarily for maintenance, and calling applications should be able to handle such a situation gracefully. Specific error responses for given methods are explained in the documentation for that method. [▲]


By default the email Marketing API processes all dates and times as UTC (both input and output). [▲]

Method Reference

GET /lists

Returns the contact lists for your server.
Method Documentation

PUT /lists/{listId}/contacts/{contactId}

Adds an existing contact with Id of {contactId} to list with Id of {listId}.
Method Documentation

PUT /lists/{listId}/contacts

Adds a contact with specified email address to list with Id of {listId}. If contact does not exist, creates one.
Method Documentation

DELETE /lists/{listId}/contacts/{contactId}

Removes contact from list. (Contact still exists and remains on other lists.)
Method Documentation

POST /contacts/unsubscribe/{contactId}

Sets the contact status to “Unsubscribe” for your server, blocking all outgoing mail to that contact across all lists and sending.
Method Documentation

GET /customfields

Get a list of all custom fields for your server.
Method Documentation

POST /customfields/{name}

Creates a new custom field for your server.
Method Documentation

DELETE /customfields/{customFieldNameId}

Deletes an existing custom field from your server.
Method Documentation

GET /content

Returns the list of email content on your server.
Method Documentation

Customers Who Trust in SocketLabs

You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.

Why SocketLabs?

What Our Customers Are Saying!