Sending a transactional email

POST https://api.expresspigeon.com/messages

JSON object represents a message to be sent.

Request parameters

Parameter Required Description
template_id Yes Newsletter template id to be sent
to Yes Email address to send message to
reply_to Yes Email address to reply to
from Yes From name, such as your name or name of your organization
subject Yes Email message subject
reply_name No Name for 'Reply-To' email field, defaults to 'from'
from_address No Email for 'From' email field, defaults to 'reply_to'
merge_fields No Values for merge fields
headers No Custom headers
view_online No Generates online version of sent message. We will host this generated message on our servers, default is false
click_tracking No Overwrites all URLs in email to point to http://clicks.expresspigeon.com for click tracking. Setting it to false will preserve all URLs intact, but click tracking will not be available, default is true
suppress_address No If true suppresses insertion of sender's physical address in the email, default is false
dictionaries No List of dictionaries to source merge fields from. Dictionary values override all other values (from merge_fields) in case of name collisions. See Dictionaries section for more information.
flow No Trigger to start a flow in case of open or click in email.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000"
    -H "Content-type: application/json"
    -d \
    '{
        "template_id": 123,
        "reply_to": "john@example.net",
        "from": "John",
        "to": "jane@example.net",
        "subject": "Dinner served",
        "merge_fields": {
            "first_name": "John",
            "menu": "<table><tr><td>Burger:</td></tr><tr>$9.99<td></td></tr></table>"
            },
        "headers": {
                    "X-custom1": "custom headervalue"
                    },
        "dictionaries": ["dict1","dict2"],
        "flow": {
            "id": 321, 
            "trigger": "click"
        }
    }'
'https://api.expresspigeon.com/messages'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import org.javalite.http.Http;
import static org.javalite.common.Collections.map;
import static org.javalite.common.Collections.list;
import static org.javalite.common.JsonHelper.toJsonString;
import static org.javalite.common.JsonHelper.toMap;

String content = toJsonString(map("template_id", 123,
        "reply_to", "john@example.net",
        "from", "John",
        "to", "jane@example.net",
        "subject", "Dinner served",
        "merge_fields", map("first_name", "John", "menu", "<table class='report'><tr><td>Burger:</td></tr><tr>$9.99<td></td></tr></table>"),
        "dictionaries", list("dict1", "dict2")
));
String response = Http.post("https://api.expresspigeon.com/messages", content)
        .header("X-auth-key", AUTH_KEY)
        .header("Content-type", "application/json")
        .text();
Map<String, Object> result = toMap(response);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
$data = array(
  'template_id' => 123,
  'reply_to' => 'john@example.net',
  'from' => 'John',
  'to' => 'jane@example.net',
  'subject' => 'Dinner served',
  'merge_fields' => array('first_name' => 'John', 'menu' => '<table class=\'report\'><tr><td>Burger:</td></tr><tr>$9.99<td></td></tr></table>'),
  'dictionaries' => array('dict1', 'dict2')
);
$options = array(
  'http' => array(
    'method' => 'POST',
    'content' => json_encode($data),
    'header' => "Content-Type: application/json\r\n" .
                "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
    )
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/messages', false, $context);
$response = json_decode($result);
1
2
3
4
5
require 'expresspigeon-ruby'

response = ExpressPigeon::API.messages.send_message template_id, 'john@example.com', 'jane@example.com', "Jane Doe",  
                                        "Let's go out for dinner?", 
                                        { first_name: 'John', meetup_place: 'Downtown' }
1
2
3
4
5
6
7
from expresspigeon import ExpressPigeon

api = ExpressPigeon()
response = api.messages.send_message(template_id=123,
                                      to="jane@example.net",
                                      reply_to="john@example.net", from_name="John", subject="Dinner served",
                                      merge_fields={"first_name": "John", "menu": "<table><tr><td>Burger:</td></tr><tr>$9.99<td></td></tr></table>})

The code above also shows that it is possible to inject HTML chunks into specific placeholders inside your email template.

NOTE: It is important to use only single quotes in injected HTML

Example Response

1
2
3
4
5
6
{
    "status": "success",
    "code": 200,
    "id": 1234,
    "message": "email queued"
}

In the call above, the id represents an ID of a message that was sent. You can use this value in order to get a report on the status of this message.

Flow usage

As mentioned in a Request parameters, one of the parameters is a flow:

"flow": {
            "id": 321, 
            "trigger": "click"
        }

If you want to trigger a Flow when a contact opens your transactional message, use this parameter:

"flow": {
            "id": 321, 
            "trigger": "open"
        }

Unlike a regular transactional message, these parameters require that the contact exists on your account.

In other words, if you use the flow parameter and the email you are sending does not exist on your account as a contact, you will get the following response:

{
    "status": "error",
    "code": 400,
    "message": "this contact does not exist: 'jane@example.net', but required to trigger a flow" 
}

A flow based on an open or a click trigger will only start for a contact once regardless how many times that contact will open or click the same message.

For more information on flows, please refer to Flows and Flow API.