Send a Transactional Email

Overview

Transaction emails are once-off emails to one or more recipients. You can use this request to send emails up to your defined quota.

The Method

API	-	Method
REST	POST	https://[Your URL]/api/2.0/trans_mails
XML-RPC	Call	transactional._mails.CreateTransactionalMail

Your URL is the address of your install.

Your method must be structured as follows:

CreateTransactionalMail(\struct | array $headers, \struct | array $body, \struct | array $attachments, \struct | array $options) : array

Parameters

Property	Type	Description
$headers	structarray	An array of headers to use when sending the email.
$body	structarray	An array containing at least a text or an HTML element, defining the body of the email.
$attachments	structarray	An array containing the attachments for the email.
$options	structarray	An array containing sending options to use when sending the mail.

Properties

For each of the parameters listed above, there are a variety of properties you can specify.

Parameter	Property	Type	Description	Default	Required	Example
$headers	from	array	The ‘From’ email address. If multiple email addresses are found in the array the first one will be used.	none	yes	$headers[‘from’] = array(‘[email protected]’ => ‘From name’)
	reply_to	array	The ‘Reply-to’ email address. If multiple email addresses are found in the array the first one will be used.	none	yes	$headers[‘reply_to’] = array(‘[email protected]’ => ‘Reply name’)
	to	array	The email addresses to send to. This field can contain multiple email addresses to send to and a new transaction will be created for each address. (Only when “Keep transactions private” is active on your customer settings.) Multiple email addresses will result in a the transactions queued for batch sending. If the value of the array is an array then this array will be used for personalising the content of the mail.	none	yes	$headers[‘to’] = array(’[email protected]’ => ‘Email1 name’, ’[email protected]’ => array(‘name’ => ‘Email2 name’, ‘custom_tags’ => ‘custom_value’))
	cc	array	The email addresses to cc the mail to. This field can contain multiple email addresses.	none	no	$headers[‘cc’] = array(’[email protected]’ => ‘Email1 name’, ’[email protected]’ => ‘Email2 name’)
	subject	string	The subject of the email to be sent.	none	yes	$headers[‘subject’] = ‘Example subject’
	trans-group-name	string	The name of the category to store the transaction under.	none	no	$headers[‘trans-group-name’] = ‘Statements’
	trans-{customfield}	string	Custom data to assign to the header of the mail. All custom fields must begin with `trans-`.	none	no	$headers[‘trans-custom-id’] = ‘Ae4537gi974’
$body	html	string	The HTML body of the mail to be sent.	none	no	$body[‘html’] = ‘ … ‘
	text	string	The text part of the mail to be sent.	none	no	$body[‘text’] = ‘Text part’
$attachments	filename	string	The name of the attachment file.	none	yes	$attachments[][‘filename’] = ‘image.jpg’
	data	base64 encoded string	The base64_encoded data of the file attachment.	none	yes	$attachments[][‘data’] = ‘/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQF’
	content_id	string	The content ID of an embedded image. A matching content ID must be found in the HTML.	none	no	$attachments[][‘content_id’] = ‘[email protected]’
$options	track_opens	string	Whether to track opens for this transaction.	yes	no	$options[‘track_opens’] = ‘no’
	track_links	string	Whether to track the links for this transaction.	yes	no	$options[‘track_links’] = ‘no’
	batch_send	string	If set to ‘yes’ transactions will be queued for sending instead of sending each one immediately.	no	no	$options[‘batch_send’] = ‘yes’
	unsubscribe_redirect_url	string	Takes a URL value to redirect to	none	no	https://www.domain.com/

Responses

Type	Description	Example
array	An array containing transaction the ID.	array(‘transaction_id’ => ‘2wBDAAUDBAQEA21234f001’)

Code Samples

This is an example of the JSON for a request.

<?php

$curl = curl_init();

$auth = base64_encode($username . ':' . $apikey);
$headers[] = 'Authorization: Basic ' . $auth;
$headers[] = 'Content-Type: application/json';
curl_setopt_array($curl, array(
  CURLOPT_URL => '(Your Url)/api/2.0/trans_mails',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "headers": {
        "from":[email protected],
        "reply_to":[email protected],
        "to":[email protected],
        "subject":"Test"
    },
    "body": {
        "html":"Example body",
        "text":"Example Text"
    },
    "attachments":[{
        "filename" => "image.jpg",
        "data" => "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQF"
}]
}',
  CURLOPT_HTTPHEADER => $headers
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

This is an simple example of sending a transaction.

$headers = array(
  'to' => array('[email protected]' => 'Email name'),
  'from' => array('[email protected]' => 'From name'),
  'trans-group-name' => 'Custom group',
  'subject' => 'Example subject',
);
$body = array(
  'html' => 'Example body',
  'text' => 'Example Text',
);
$attachments[] = array(
  'filename' => 'image.jpg',
  'data' => '/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQF',
);
$options = array();
$result = $api->send($header, $body, $attachments, $options);
$transaction = $api->get($result['transaction_id']);