Guides
Guides

Using the Transactional API

Suggest Edits

Using the BigMailer API you can trigger transactional campaign emails from your application. The first step is creating and configuring a transactional campaign within the BigMailer console. Configuring a transactional campaign entails entering the from address, subject line, body, and other content related details of the campaign. The second step is integrating a call to the BigMailer transactional API within your application. Before adding API calls into your application code, please read our guide on getting started with the API.

In addition to sending an email, the transactional API stores the email address and field values of the contact provided in the API call. If the email address does not exist the contact is created. If the email address exists the contact is updated. In either case, the contact is added to the list you select while configuring the transactional campaign.

API Key, Brand ID, Campaign ID

To configure API calls from your application you need three values: An API key, the brand ID, and the campaign ID. An API key is created using the API key management page. The brand ID is obtained from the brand's settings page. The campaign ID is obtained from the campaigns "API Settings" tab.

The API key is passed in the header X-API-Key. The brand ID and campaign ID are used to construct the URL of the API call (see examples below).

3636

Location of the API key, brand ID, and campaign ID

Request Body

There are three data points that can be specified in the request body: email, field values, and variables.

The email is used as the email address of the contact to receive the campaign.

Both field values and variables are used to replace merge tags (ex *|FIRST NAME|*) that you may have specified in the body, subject line, and other parts of your campaign. The primary difference is that field values are stored as part of the contact, while variables are not. Variables are used to fill in merge tags and are then discarded. Field values are used to fill in merge tags and are then stored alongside the email address of the contact. Field values may subsequently be used to segment your lists and to fill in merge tags in future campaigns.

Here is an example request body:

{
  "email": "[email protected]",
  "field_values": [
    {
      "name": "FIRST_NAME",
      "string": "Christopher"
    },
    {
      "name": "AGE",
      "integer": 38
    },
    {
      "name": "DOB",
      "date": "1981-12-04"
    }
  ],
  "variables": [
    {
      "name": "SPECIAL_MESSAGE",
      "value": "<strong>Thank you for being a great customer!</strong>"
    }
  ],
}

See our API reference for more details on structuring transactional calls.

Sample Code

BRAND_ID="YOUR BRAND ID"
CAMPAIGN_ID="YOUR CAMPAIGN ID"
API_KEY="YOUR API KEY"

curl --request POST \
  --url https://api.bigmailer.io/v1/brands/$BRAND_ID/transactional-campaigns/$CAMPAIGN_ID/send \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $API_KEY" \
  --data '{"field_values":[{"name":"FIRST_NAME","string":"Christopher"},{"name":"AGE","integer":38},{"name":"DOB","string":"1981-12-04"}],"variables":[{"name":"SPECIAL_MESSAGE","value":"<strong>Thank you for being a great customer!</strong>"}],"email":"[email protected]"}'

const fetch = require('node-fetch');

let brandId = 'YOUR BRAND ID';
let campaignId = 'YOUR CAMPAIGN ID';
let apiKey = 'YOUR API KEY';

let url = `https://api.bigmailer.io/v1/brands/${brandId}/transactional-campaigns/${campaignId}/send`;

let options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: '{"field_values":[{"name":"FIRST_NAME","string":"Christopher"},{"name":"AGE","integer":38},{"name":"DOB","string":"1981-12-04"}],"variables":[{"name":"SPECIAL_MESSAGE","value":"<strong>Thank you for being a great customer!</strong>"}],"email":"[email protected]"}'
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

brand_id = "YOUR BRAND ID"
campaign_id = "YOUR CAMPAIGN ID"
api_key = "YOUR API KEY"

url = URI("https://api.bigmailer.io/v1/brands/#{brand_id}/transactional-campaigns/#{campaign_id}/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["X-API-Key"] = api_key
request.body = "{\"field_values\":[{\"name\":\"FIRST_NAME\",\"string\":\"Christopher\"},{\"name\":\"AGE\",\"integer\":38},{\"name\":\"DOB\",\"string\":\"1981-12-04\"}],\"variables\":[{\"name\":\"SPECIAL_MESSAGE\",\"value\":\"<strong>Thank you for being a great customer!</strong>\"}],\"email\":\"[email protected]\"}"

response = http.request(request)
puts response.read_body

import requests

brand_id = "YOUR BRAND ID"
campaign_id = "YOUR CAMPAIGN ID"
api_key = "YOUR API KEY"

url = f"https://api.bigmailer.io/v1/brands/{brand_id}/transactional-campaigns/{campaign_id}/send"

payload = {
    "field_values": [
        {
            "name": "FIRST_NAME",
            "string": "Christopher"
        },
        {
            "name": "AGE",
            "integer": 38
        },
        {
            "name": "DOB",
            "string": "1981-12-04"
        }
    ],
    "variables": [
        {
            "name": "SPECIAL_MESSAGE",
            "value": "<strong>Thank you for being a great customer!</strong>"
        }
    ],
    "email": "[email protected]"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-API-Key": api_key,
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

<?php

$brandId = "YOUR BRAND ID";
$campaignId = "YOUR CAMPAIGN ID";
$apiKey = "YOUR API KEY";

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bigmailer.io/v1/brands/$brandId/transactional-campaigns/$campaignId/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"field_values\":[{\"name\":\"FIRST_NAME\",\"string\":\"Christopher\"},{\"name\":\"AGE\",\"integer\":38},{\"name\":\"DOB\",\"string\":\"1981-12-04\"}],\"variables\":[{\"name\":\"SPECIAL_MESSAGE\",\"value\":\"<strong>Thank you for being a great customer!</strong>\"}],\"email\":\"[email protected]\"}",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Content-Type: application/json",
    "X-API-Key: $apiKey,
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Updated about 4 years ago