Messages


messagesSend

Send a new transactional e-mail message through LeaderSend

 

Description
array messagesSend ( array $request )

 

Parameters
$request
array

The information on the message to send.

to
array

An array of recipient information

to[]
struct|string

A single recipient’s information

email *
string

The email address of the recipient. Required.

name
string

The optional display name to use for the recipient.

from[]
struct

A sender’s information.

email * string

The sender email address.

name
string

The optional from name used by sender.

html
string

The full HTML content to be sent.

plain
string

Optional full text content to be sent.

subject *
string

The message subject.

headers
array

Optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed).

keep_recipients
boolean

Whether or not to expose all recipients in to "To" header for each email. Default true.

auto_html
boolean

Whether or not to automatically generate an HTML part for messages that are not given HTML. Default false.

auto_plain
boolean

Whether or not to automatically generate a text part for messages that are not given text. Default false.

attachments
array

An array of supported attachments to add to the message.

attachments[]
struct

A single supported attachment.

content
string

The content of the attachment as a base64-encoded string.

name
string

The file name of the attachment.

type
string

The MIME type of the attachment.

images
array

An array of embedded images to add to the message.

images[]
struct

A single embedded image.

content
string

The content of the image as a base64-encoded string.

name
string

The file name of the image.

type
string

The MIME type of the image - must start with "image/"

cid
string

The Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content

merge_vars
array

Recipient merge variables.

merge_vars[]
array

per-recipient merge variables

merge_vars[<recipient_email_addres>]
string

The email address of the recipient that the merge variables should apply to.

merge_vars[<recipient_email_addres>][] struct

The recipient’s merge variables

merge_vars[<recipient_email_addres>][]
struct

A single merge variable.

merge_vars[<recipient_email_addres>][<merge_variable_name>]
string

The merge variable's name. Merge variable names are case-insensitive and may not start with _

merge_vars[<recipient_email_addres>][<merge_variable_name>] *
string

The merge variable's content.

tracking
array

An associative array of options to enable or disabled any kind of statistics.

tracking[opens]
boolean

Whether or not to turn on open tracking for the message. Default false.

tracking[html_clicks]
boolean

Whether or not to turn on click tracking for the HTML message. Default false.

tracking[plain_clicks]
boolean

Whether or not to turn on click tracking for the plain message. Default false.

tracking[domain]
string

Custom domain to use for tracking opens and clicks

analytics
array

Additional parameters for Google Analytics.

analytics[campaign]
string

The name of the campaign (append to the link as &utm_campaign=<campaign_name>).

tags
array

An array of string to tag the message with.

tags[]
string

A single tag.

template
string

The name (slug) of template which is used for sending email.

If you are using template you do not need to use several request parameters:

  • email subject (parameter subject);
  • sender's email and/or name (parameter from);
  • email HTML body (parameter html) and/or email plain text part (parameter plain).

You can create your templates in section "Templates" of your LeaderSend's profile.

signing_domain *
string

Authenticated domain name for sending emails.

In order to be able to send emails from LeaderSend, you need to verify the email sender's identity. It means that your from email address domain name must be verified to prove that you can access and use this domain. Domain verification consists of two TXT type DNS entries in your domain DNS: DKIM and SPF. In order to authenticate your domain, you need to have access your domain DNS entries and domain DNS should support TXT entries. To add your verified domain in LeaderSend account, go to the "Settings & Support" section and choose "Sending Domain".

 

Return value
array

An array of structs with information for each recipient.

return[]
struct

The sending results for a single recipient.

email
string

The email address of the recipient.

status
string

The sending status of the recipient - either "sent" or "rejected".

reject_reason
string

The reason for the rejection if the recipient status is "rejected".

id
string

The message's unique id.

 

Examples

<?php
include_once('Leadersend.class.php');
$apikey 'YOUR_API_KEY'// specify your key
$LS = new Leadersend($apikey);

// generate HTML part of dynamic email message
$htmlPart = <<<HTML
<p>Hi, #[FNAME]# #[LNAME]#!</p>
<p>Thanks for registering in our system.</p>
<p>Please click <a href="http://company.com/your_confirm_link_here/">here</a> to confirm your registration.</p>
#[IF:EMAIL=test@company.com]# <p>dynamic content specially for Alex</p> #[/IF]#
HTML;

$request = array(
    
'subject' => 'Test transactional email'// required
    
'from'    => array( // required. A sender’s information
        
'name'  => 'John Doe',
        
'email' => 'john@doe.com'
    
),
    
'to' => array( // required. A list of recipients
        // recipient #1 with name and email
        
array(
            
'name'  => 'Alex',
            
'email' => 'test@company.com'
        
),
        
// recipinet #2 with just email
        
'test@example.com'
    
),
    
'html'       => $htmlPart// email's HTML content
    
'auto_plain' => true// automatically generate a text part for the messages of HTML part
    
'merge_vars' => array( // define merge variables for each recipient
        
'test@company.com' => array(
            array(
                
'name'  => 'FNAME',
                
'value' => 'Alex'
            
),
            array(
                
'name'  => 'LNAME',
                
'value' => 'Doubt'
            
)
        ),
        
'email@example.com' => array(
            array(
                
'name'  => 'FNAME',
                
'value' => 'Jennifer'
            
),
            array(
                
'name'  => 'LNAME',
                
'value' => 'McQuin'
            
)
        )
    ),
    
'signing_domain' => 'doe.com' // required
);
$response $LS->messagesSend($request);
if (
$LS->errorCode){
    
printf("Error (%s): %s"$LS->errorCode$LS->errorMessage);
} else {
    echo 
"Response:\n";
    
print_r($response);
    
/*
    Array
    (
        [0] => Array
            (
                [email] => test@example.com
                [status] => reject
                [reject_reason] => Invalid Email Address: test@example.com
                [id] => 79778fb6199ff8985b61dfd7a1334dab
            )
    
        [1] => Array
            (
                [email] => test@company.com
                [status] => sent
                [id] => 8a1dd5084eb6330f8d8db762dceea288
            )
    
    )
    */
}
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using System.Reflection;
using System.Reflection.Emit;
using System.IO;

using Leadersend;
using Leadersend.ErrorHandling;
using Leadersend.DataObject;

namespace LeadersendTest
{
    class Test
    {
        private string apikey;
        public Wrapper api;

        public Test(string apikey)
        {
            this.apikey = apikey;
            this.api = new Wrapper(this.apikey);
        }

        public void messages_send()
        {
            var message = new LSMessage()
            {
                subject = "Test transactional email", // required
                from = new Dictionary<string, string>(){ // required. A sender’s information
                    {"name", "John Doe"},
                    {"email", "john@doe.com"}
                },
                to = new List<object>() {
                    new Dictionary<string, string>() {// required. A list of recipients
                        {"name", "Alex"},
                        {"email", "test@company.com"}
                    },
                    // recipinet #2 with just email
                    "test@example.com"
                },
                // email's HTML content
                html = @"<p>Hi, #[FNAME]# #[LNAME]#!</p>
<p>Thanks for registering in our system.</p>
<p>Please click <a href=""http://company.com/your_confirm_link_here/"">here</a> to confirm your registration.</p>
#[IF:EMAIL=test@company.com]# <p>dynamic content specially for Alex</p> #[/IF]#",
                auto_plain = true, // automatically generate a text part for the messages of HTML part
                merge_vars = new Dictionary<string, List<Dictionary<string, string>>>() { // define merge variables for each recipient
                    {"test@company.com", new List<Dictionary<string, string>>() {
                        new Dictionary<string, string>() {
                            {"name", "FNAME"},
                            {"value", "Alex"}
                        },
                        new Dictionary<string, string>() {
                            {"name", "LNAME"},
                            {"value", "Doubt"}
                        }
                    }},
                    {"email@example.com", new List<Dictionary<string, string>>() {
                        new Dictionary<string, string>() {
                            {"name", "FNAME"},
                            {"value", "Jennifer"}
                        },
                        new Dictionary<string, string>() {
                            {"name", "LNAME"},
                            {"value", "McQuin"}
                        }
                    }},
                }
            };

            IEnumerable<LSMessageResponse> responses = this.api.messagesSend(message);
            Console.WriteLine("Success!");
            foreach (LSMessageResponse response in responses)
            {
                Console.WriteLine(response.email + " = " + response.status);
                Console.WriteLine("\tmessage-id = " + response.id);
            }
        }

        static void Main(string[] args)
        {
            try
            {
                Test t = new Test("<API_KEY>");
                t.messages_send();

            }
            catch (LeadersendException e)
            {
                Console.WriteLine("error message: " + e.Message);
                Console.WriteLine("error code: " + e.ErrorCode);
            }
            Console.WriteLine("\nFinished.\n");
        }
    }
}

 

Error Codes
Method-specific Errors
30 Invalid email address.
31 Specified email address looks fake or is invalid. You must provide a real email address.
34 Request size for the API call is to big - more detail in the actual message returned.
36 You must specify an authenticated sending domain (read more information here).
37 No authentication - unknown sending domain (read more information here).
38 Maximum bulk email recipients limit reached. Please contact support.
103 The account being accessed has no active plan.
104 You have reached sending limit per day.
105 Provided API key is invalid.
106 Non-verified client reached daily sending limit.
107 Waiting for account verification.
108 There are no email credits in the account.
109 Hourly sending limit has been reached. Please wait until next hour or upgrade your account.
 
Global API Call Errors
10 You must specify value for the parameter reported in actual error message.
11 Invalid parameter type.
12 Parameter reported in actual message is required.
 
System General Errors
-1 System temporary is unavailable.
-2 Requested API method is not supported.
-3 Unknown error.
-98 We are running system maintenance.

 


messagesSendRaw

Take a raw MIME document for a message, and send it exactly as if it were sent over the SMTP protocol.

 

Description
array messagesSendRaw ( array $request )

 

Parameters
$request
array

The information on the message to send.

to
array

Optionally define the recipients to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document.

to[]
struct|string

A single recipient’s information

email *
string

The email address of the recipient. Required.

name
string

The optional display name to use for the recipient.

raw *
string

The full MIME document of an email message.

signing_domain *
string

Authenticated domain name for sending emails.

In order to be able to send emails from LeaderSend, you need to verify the email sender's identity. It means that your from email address domain name must be verified to prove that you can access and use this domain. Domain verification consists of two TXT type DNS entries in your domain DNS: DKIM and SPF. In order to authenticate your domain, you need to have access your domain DNS entries and domain DNS should support TXT entries. To add your verified domain in LeaderSend account, go to the "Settings & Support" section and choose "Sending Domain".

 

Return value
array

An array of structs with information for each recipient.

return[]
struct

The sending results for a single recipient.

email
string

The email address of the recipient.

status
string

The sending status of the recipient - either "sent" or "rejected".

reject_reason
string

The reason for the rejection if the recipient status is "rejected".

id
string

The message's unique id.

 

Examples

<?php
include_once('Leadersend.class.php');
$apikey 'YOUR_API_KEY'// specify your key
$LS = new Leadersend($apikey);

// generate full MIME document for the message
$mimeEmail = <<<MIME
Subject: Test transactional raw email
From: John Doe <john@doe.com>
MIME-Version: 1.0
Content-Type: multipart/alternative;
    boundary="b1_0d10f8e7346416e35169c0a715b306ae"

--b1_0d10f8e7346416e35169c0a715b306ae
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable

Hi, Customer !

Thanks for registering in our system.

Please click here:
http://company.com/your_confirm_link_here/ to confirm your registration.

--b1_0d10f8e7346416e35169c0a715b306ae
Content-Type: text/html; charset = "utf-8"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<body>
<p>Hi, Customer !</p>
<p>Thanks for registering in our system.</p>
<p>Please click <a href=3D"http://company.com/your_confirm_link_here/">here</a> to confirm your registration.</p>
</body>
</html>

--b1_0d10f8e7346416e35169c0a715b306ae--
MIME;

$request = array(
    
'to' => array(    // required. A list of recipients
        // recipient #1 with name and email
        
array(
            
'name'  => 'Jennifer',
            
'email' => 'test@company.com'
        
),
        
// recipinet #2 with just email
        
'test@example.com'
    
),
    
'raw' => $mimeEmail,
    
'signing_domain' => 'doe.com'
);
$response $LS->messagesSendRaw($request);
if (
$LS->errorCode){
    
printf("Error (%s): %s"$LS->errorCode$LS->errorMessage);
} else {
    echo 
"Response:\n";
    
print_r($response);
    
/*
    Array
    (
        [0] => Array
            (
                [email] => test@example.com
                [status] => reject
                [reject_reason] => Invalid Email Address: test@example.com
                [id] => 5da26b90871a46ade351b164718d7162
            )
    
        [1] => Array
            (
                [email] => test@company.com
                [status] => sent
                [id] => 3e61bfba2de5932538fcb9fa34aeeb19
            )
    
    )
    */
}
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using System.Reflection;
using System.Reflection.Emit;
using System.IO;

using Leadersend;
using Leadersend.ErrorHandling;
using Leadersend.DataObject;

namespace LeadersendTest
{
    class Test
    {
        private string apikey;
        public Wrapper api;

        public Test(string apikey)
        {
            this.apikey = apikey;
            this.api = new Wrapper(this.apikey);
        }

        public void messages_send_raw()
        {
            var message = new LSMessageRaw()
            {
                to = new List<object>() {
                    new Dictionary<string, string>() {// required. A list of recipients
                        {"name", "Alex"},
                        {"email", "test@company.com"}
                    },
                    // recipinet #2 with just email
                    "test@example.com"
                },
                raw = @"Subject: Test transactional raw email
From: John Doe <john@doe.com>
MIME-Version: 1.0
Content-Type: multipart/alternative;
    boundary=""b1_0d10f8e7346416e35169c0a715b306ae""

--b1_0d10f8e7346416e35169c0a715b306ae
Content-Type: text/plain; charset=""utf-8""
Content-Transfer-Encoding: quoted-printable

Hi, Customer !

Thanks for registering in our system.

Please click here:
http://company.com/your_confirm_link_here/ to confirm your registration.

--b1_0d10f8e7346416e35169c0a715b306ae
Content-Type: text/html; charset = ""utf-8""
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html PUBLIC ""-//W3C//DTD HTML 4.01//EN"">
<html>
<body>
<p>Hi, Customer !</p>
<p>Thanks for registering in our system.</p>
<p>Please click <a href=3D""http://company.com/your_confirm_link_here/"">here</a> to confirm your registration.</p>
</body>
</html>

--b1_0d10f8e7346416e35169c0a715b306ae--"
            };

            IEnumerable<LSMessageResponse> responses = this.api.messagesSendRaw(message);
            Console.WriteLine("Success!");
            foreach (LSMessageResponse response in responses)
            {
                Console.WriteLine(response.email + " = " + response.status);
                Console.WriteLine("\tmessage-id = " + response.id);
            }
        }

        static void Main(string[] args)
        {
            try
            {
                Test t = new Test("<API_KEY>");
                t.messages_send_raw();

            }
            catch (LeadersendException e)
            {
                Console.WriteLine("error message: " + e.Message);
                Console.WriteLine("error code: " + e.ErrorCode);
            }
            Console.WriteLine("\nFinished.\n");
        }
    }
}

 

Error Codes
Method-specific Errors
30 Invalid email address.
31 Specified email address looks fake or is invalid. You must provide a real email address.
34 Request size for the API call is to big - more detail in the actual message returned.
36 You must specify an authenticated sending domain (read more information here).
37 No authentication - unknown sending domain (read more information here).
38 Maximum bulk email recipients limit reached. Please contact support.
103 The account being accessed has no active plan.
104 You have reached sending limit per day.
105 Provided API key is invalid.
106 Non-verified client reached daily sending limit.
107 Waiting for account verification.
108 There are no email credits in the account.
109 Hourly sending limit has been reached. Please wait until next hour or upgrade your account.
 
Global API Call Errors
10 You must specify value for the parameter reported in actual error message.
11 Invalid parameter type.
12 Parameter reported in actual message is required.
 
System General Errors
-1 System temporary is unavailable.
-2 Requested API method is not supported.
-3 Unknown error.
-98 We are running system maintenance.

 


messagesInfo

Get the information for a single sent message.

 

Description
array messagesInfo ( array $request )

 

Parameters
$request
array

The information of the message to get detailed information.

id *
string

The unique id of the message to get - passed as the "id" field in send calls.

 

Return value
struct

The information for the message.

email
string

The recipient email address.

status
string

Sending status of this message: sent or rejected.

id
string

The message's unique id.

timestamp
integer

The Unix timestamp from when this message was sent.

sender
string

The email address of the sender.

subject
string

The message's subject line.

tags
array

List of tags on this message.

tags[]
string

Individual tag on this message.

opens
integer

How many times has this message been opened.

Note that email opening statistics are updated every 5 minutes.

opens_details
array

List of individual opens for the message.

opens_details[]
struct

Information on an individual open.

timestamp
integer

The Unix timestamp from when the message was opened.

ip
string

The IP address that generated the open.

user_agent
string

The email client or browser data of the open.

clicks
integer

How many times has a link been clicked in this message.

clicks_details
array

List of individual clicks for the message.

clicks_details[]
struct

Information on an individual click.

timestamp
integer

The Unix timestamp from when the message was clicked.

ip
string

The IP address that generated the click.

url
string

The URL that was clicked on.

 

Examples

<?php

include_once('Leadersend.class.php');
$apikey 'YOUR_API_KEY'// specify your key
$LS = new Leadersend($apikey);

$request = array(
    
'id' => '82b50087a832f98bd07856ea81e3a4dd' // required
);
$response $LS->messagesInfo($request);
header("Content-Type: text/plain");
if (
$LS->errorCode){
    
printf("Error (%s): %s"$LS->errorCode$LS->errorMessage);
} else {
    echo 
"Response:\n";
    
print_r($response);
    
/*
    Array
    (
        [email] => test@example.com
        [status] => sent
        [id] => 82b50087a832f98bd07856ea81e3a4dd
        [timestamp] => 1390812586
        [sender] => john@doe.com
        [subject] => Confirm your registration
        [tags] => Array
            (
                [0] => registration
            )
    
        [opens] => 1
        [opens_details] => Array
            (
                [0] => Array
                    (
                        [timestamp] => 1390812630
                        [ip] => 159.148.135.129
                        [user_agent] => Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1700.76 Safari/537.36
                    )
    
            )
    
        [clicks] => 1
        [clicks_details] => Array
            (
                [0] => Array
                    (
                        [timestamp] => 1390812630
                        [ip] => 159.148.135.129
                        [url] => http://www.example.com
                    )
    
            )
    
    )
    */
}

 

Error Codes
Method-specific Errors
35 The provided message id does not exist.
105 Provided API key is invalid.
 
Global API Call Errors
10 You must specify value for the parameter reported in actual error message.
11 Invalid parameter type.
12 Parameter reported in actual message is required.
 
System General Errors
-1 System temporary is unavailable.
-2 Requested API method is not supported.
-3 Unknown error.
-98 We are running system maintenance.

 

* required parameters