Send a Transactional Email

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
RESTPOSThttp://[Your URL]/api/2.0/trans_mails
XML-RPCCalltransactional._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

PropertyTypeDescription
$headers\structarrayAn array of headers to use when sending the email.
$body\structarrayAn array containing at least a text or an HTML element, defining the body of the email.
$attachments\structarrayAn array containing the attachments for the email.
$options\structarrayAn 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.

ParameterPropertyTypeDescriptionDefaultRequiredExample
$headersfromarrayThe 'From' email address. If multiple email addresses are found in the array the first one will be used.noneyes$headers['from'] = array('from@example.com' => 'From name')
reply_toarrayThe 'Reply-to' email address. If multiple email addresses are found in the array the first one will be used.noneyes$headers['reply_to'] = array('reply_to@example.com' => 'Reply name')
toarrayThe 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.
noneyes$headers['to'] = array('email1@example.com' => 'Email1 name', 'email2@example.com' => array('name' => 'Email2 name', 'custom_tags' => 'custom_value'))
ccarrayThe email addresses to cc the mail to. This field can contain multiple email addresses.noneno$headers['cc'] = array('email1@example.com' => 'Email1 name', 'email2@example.com' => 'Email2 name')
subjectstringThe subject of the email to be sent.noneyes$headers['subject'] = 'Example subject'
trans-group-namestringThe name of the category to store the transaction under.noneno$headers['trans-group-name'] = 'Statements'
trans-{customfield}stringCustom data to assign to the header of the mail. All custom fields must begin with `trans-`.noneno$headers['trans-custom-id'] = 'Ae4537gi974'
$bodyhtmlstringThe HTML body of the mail to be sent.noneno$body['html'] = ' ... '
textstringThe text part of the mail to be sent.noneno$body['text'] = 'Text part'
$attachmentsfilenamestringThe name of the attachment file.noneyes$attachments[]['filename'] = 'image.jpg'
database64 encoded stringThe base64_encoded data of the file attachment.noneyes$attachments[]['data'] = '/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQF'
content_idstringThe content ID of an embedded image. A matching content ID must be found in the HTML.noneno$attachments[]['content_id'] = 'image001.jpg@01CE0B63.BEC60780'
$optionstrack_opensstringWhether to track opens for this transaction.yesno$options['track_opens'] = 'no'
track_linksstringWhether to track the links for this transaction.yesno$options['track_links'] = 'no'
batch_sendstringIf set to 'yes' transactions will be queued for sending instead of sending each one immediately.nono$options['batch_send'] = 'yes'

Responses

TypeDescriptionExample
arrayAn array containing transaction the ID.array('transaction_id' => '2wBDAAUDBAQEA21234f001')

Code Samples

This is an simple example of sending a transaction.

Tutorial

The rest of this document describes the example above, step-by-step.

In our Getting Started section we covered the four important components of an API request; URL, method, headers, and body.

RequestStructure

Let's analyse the code sample above to determine where each line fits into this outline.

1. Message header array

The following code stores header details to the header parameter.

$headers = array(

'to' => array('email@example.com' => 'Email name'),

'from' => array('from@example.com' => 'From name'),

'trans-group-name' => 'Custom group',

'subject' => 'Example subject',

);

2. Message body array

The following code stores body details to the body parameter.

$body = array(

'html' => 'Example body',

'text' => 'Example Text',

);

3. Attachments array

The following code stores attachments to the attachments parameter.

$attachments[] = array(

'filename' => 'image.jpg',

'data' => '/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQF',

);

4. Tracking array

The following code keeps track of any links in the transactional mail

$options = array();

5. Send transactional mail

The following code sends the mail with the stored data in the parameters

$result = $api->send($header, $body, $attachments, $options);

6. Return result

The following code returns any results from the transactional mail sent for reporting using the transactional email's id.

$transaction = $api->get($result['transaction_id']);
Translate »