Sending a transactional email

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

JSON object represents a message to be sent.

Request parameters

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.