How To Use Sender.net’s API?

API documentation (version 1.4)

 

General info

  1. API is implemented through HTTP protocol, using POST. Responses are returned in JSON, using UTF-8 encoding.
  2. All API requests shall be directed at http://app.sender.net/api/
  3. Request data must be encoded in JSON, in POST parameter named data.
  4. Replace api_key mentioned in the documentation with your own API key (32 ASCII characters).

 

Request parameters example (JSON):
{
    "method": "listSubscribe", 
    "params": {
        "api_key": "your_api_key_here",
        "list_id": "your_list_id",
        "emails": ["email@email.com", {"email": "email@email.lt", "firstname": "John", "lastname": "Snow"}, ...]
    }
}

 

PHP code snippet for calling our api:
$url = "https://app.sender.net/api/";

$data = array(
    "method" => "listSubscribe", 
    "params" => [
		"api_key" => "98844b0f8da95e7c8ace0aaa6234e4e2",
		"list_id" => "12345",
        "emails" => [
			"name.lastname@example.com"
		]
    ]
);

$options = [
    'http' => [
        'method'  => 'POST',
        'content' => http_build_query(array('data' => json_encode($data)))
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

 

Managing subscribers
  • listSubscribe(string api_key, int list_id, array emails, bool update_existing)
    Imports the specified emails to a list.
  • listUnsubscribe(string api_key, int list_id, array emails)
    Marks the specified emails as unsubscribed.
  • listSubsribers(string api_key, int list_id)
    Returns a list of subscribers in specified list.
  • listGetAllLists(string api_key)
    Returns a list of all subscriber lists in the account.
  • listCreate(string api_key, string title)
    Creates a new list.
  • listMove(string api_key, int old_list_id, int new_list_id, array emails)
    Moves the emails from old_list_id to new_list_id.
  • listRemove(string api_key, int list_id, array emails)
    Removes emails from list_id .
Reports
  • statsCampaignReport(string api_key, int campaign_id)
    Returns overall statistics for the campaign.
  • statsCampaignOpens(string api_key, int campaign_id)
    Returns a list of emails, who opened the campaign.
  • statsCampaignUnsubscribes(string api_key, int campaign_id)
    Returns a list of emails, who unsubscribed from the campaign.
  • statsCampaignBounces(string api_key, int campaign_id)
    Returns a list of bounced emails from the campaign.
  • statsCampaignLinkReport(string api_key, int campaign_id)
    Returns a list of emails, who clicked on links in the campaign.
Campaign
  • campaignListCampaigns(string api_key)
    Returns a list of email campaigns.
  • campaignCreate(string api_key, string title, string subject, string sender_name, string sender_email, bool google_analytics, array lists, int template_id, string html_content, string text_content)
    Creates a new email campaign. Parameter lists must contain an array with list id, for example: [6436, 8967, 3233].
  • campaignStartSending(string api_key, int campaign_id)
    Starts sending a campaign.
  • campaignDelete(string api_key, int campaign_id)
    Deletes a campaign.
  • campaignCopy(string api_key, int campaign_id)
    Creates a copy of campaign.
  • campaignschedule(string api_key, int campaign_id, string schedule_date)
    Schedules a campaign to be sent later. Date/time must be specified as YYYY-MM-DD HH:MM
Transactional emails
  • sendTransactionalEmail(string api_key, int transactional_campaign_id, string email, array personalized_data)
    Sends a transactional campaign to email. Parameter personalized_data must contain an array of template variables – every variable in this array is replaced in the template, for example, a tag “{$test}” in this email would be changed to “123”.

E-Commerce

  1. E-commerce related functions are implemented through HTTP protocol, using POST. Responses are returned in JSON, using UTF-8 encoding.
  2. All API requests shall be directed at http://app.sender.net/commerce/v1/[function_name]/
  3. Replace [function_name] with one of the possible ecommerce related actions (i.e. cart_track – http://app.sender.net/commerce/v1/cart_track/)
  4. Request data is sent as an array, in POST parameter named data.
  5. Replace api_key mentioned in the documentation with your own API key (32 ASCII characters).

 

Request parameters example (php array):
array(
    "api_key" => "98844b0f8da95e7c8ace0aaa6234e4e2",
    "email" => "email@example.com",
    "external_id" => 1,
    "url" => "http://magento.sender.net/index.php/sendercommerce/cart/?hash={$cart_hash}",
    "currency" => "EUR",
    "grand_total" => 75.00,
    "products" => array(
		array(
			"sku" => "mtk004xs",
			"name" => "CHELSEA TEE",
			"price" => 75.00,
			"price_display" => "75.00 EUR",
			"qty" => 1,
			"image" => "http://magento.sender.net/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/m/t/mtk004t.jpg"
		)
	)
)

 

PHP code snippet for calling our ecommerce api:
$url = "https://app.sender.net/commerce/v1/cart_track";

$data = array(
	"api_key" => "98844b0f8da95e7c8ace0aaa6234e4e2",
	"email" => "email@example.com",
	"external_id" => 1,
	"url" => "http://magento.sender.net/index.php/sendercommerce/cart/?hash={$cart_hash}",
	"currency" => "EUR",
	"grand_total" => 75.00,
	"products" => array(
		array(
			"sku" => "mtk004xs",
			"name" => "CHELSEA TEE",
			"price" => 75.00,
			"price_display" => "75.00 EUR",
			"qty" => 1,
			"image" => "http://magento.sender.net/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/m/t/mtk004t.jpg"
		)
	)
);

$options = [
    'http' => [
        'method'  => 'POST',
        'content' => http_build_query($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

 

Ecommerce methods
  • cart_track
    Creates or updates a cart and it‘s contents.
    This method is used when a customer adds a product to his cart. If he had no products in his cart, the cart is created, but if a customer adds products to a cart that is not empty, the cart contents are updated.

POST data:

array(
    "api_key" => string api_key,
    "email" => string email (customer‘s email),
    "external_id" => integer external_id (cart‘s id in your system),
    "url" => string url (cart‘s url in your system used to access the cart from outside),
    "currency" => string currency,
    "grand_total" => float grand_total (precision 2),
    "products" => array array(
        array array(
            "sku" => string sku,
            "name" => string name,
            "price" => float price (precision 2),
            "price_display" => string price_display,
            "qty" => integer qty,
            "image" => string image (image url)
        )
    )
)
  • cart_delete
    Deletes cart and its contents.
    This method is used when a customer deletes all products out of his cart.

POST data:

array(
    "api_key" => string api_key,
    "external_id" => integer external_id (cart‘s id in your system)
)
  •  cart_convert
    Marks cart as converted(purchased).
    This method is used when a customer completes the purchase of his cart.

POST data:

array(
    "api_key" => string api_key,
    "external_id" => integer external_id (cart‘s id in your system)
)
E-commerce: JSON for product import in Sender campaign editor

If you wish to seamlessly import product information into a campaign, which you have created in Sender, you will need to add the following JSON script to your product page:

<script type="application/sender+json">
    {
      "name": string "Product name",
      "image": string "Product image link (i.e. https://example.com/image.jpg)",
      "description": string "Product description",
      "price": float(precision 2)/double(precision 2) Product (i.e. 99.99),
      "special_price": float(precision 2)/double(precision 2) Special product price (i.e. 71.99) (If there is no special price, please provide the same price here),
      "currency": string "Currency (i.e. EUR)",
      "quantity": integer Product quantity in storage (i.e. 29),
      "rating": float(precision 1)/double(precision 1) Product rating (i.e. 4.6) (this parameter is optional)
    }
</script>

 

Tagged: