Syntax
object sendTransactionalEmail( string api_key, string transactional_group, int list_id, array contacts, string subject, string from_address, string from_name, string html_content, [ string text_content, array stored_fields, boolean ignore_unsubscribers ] );
API Key Access Level required: Standard access
Parameters
api_key
(string)The key required to access the API. See Getting Started for more information.
transactional_group
(string)The name of the Transactional Group for reporting of send statistics. See Transactional Overview for more information.
list_id
(int)The ID of the List where supplied Contacts will be added or updated.
contacts
(array)An array containing one or more associative arrays of Contact details. The Contact details are indexed using each of the Field names or by Field ID in the List. See the examples below.
subject
(string)The email subject.
from_address
(string)A valid sender email address.
from_name
(string)The name of the sender.
html_content
(string)The HTML content for the email.
text_content
(string - optional)The text content for the email.
stored_fields
(array - optional)To save Field values to new Contacts the Field name or Field ID must be provided within this array. Email and mobile number fields are always saved.
ignore_unsubscribers
(boolean - optional)By default all unsubscribed email addresses for the list supplied will not receive Messages. To ignore this behaviour set this to
true
.
Return Value
Returns an object containing the Batch ID, List ID and Contact IDs of added Contacts. The Contact IDs object is indexed using the corresponding index in the supplied contacts
array.
Examples
The following example sends a transactional email Message to three Contacts:
PHP
$list_id = 1234567;
$contacts = array(
array(
'First Name' => 'Alice',
'Email' => 'alice@example.com'
),
array(
'First Name' => 'Bob',
'Email' => 'bob@example.com'
),
array(
'field_75698' => 'Sam',
'field_46899' => 'sam@example.com'
),
);
$subject = 'Thank you for subscribing';
$from_address = 'my_company@example.com';
$from_name = 'My Company';
$html_content = '<html><body><p>We have noticed that you recently subscribed for our newsletter</p></body></html>';
$api = new Api($url, 'YOURAPIKEY');
$transactional_result = $api->invokeMethod('sendTransactionalEmail', $group_name, $list_id, $contacts, $subject, $from_address, $from_name, $html_content);
// loop over the result
foreach ($contact_ids as $index => $contact_id) {
print $contacts[$index]['Email'] ." was sent a Message and was successfully added as Contact ". $contact_id ."\n";
}
JSON Request
"id": 1,
"method": "sendTransactionalEmail",
"params": [
"YOURAPIKEY",
1234567,
[
{
"First Name": "Alice",
"Email": "alice@example.com"
},
{
"First Name": "Bob",
"Email": "bob@example.com"
},
{
"field_75698": "Sam",
"field_46899": "sam@example.com"
}
],
"subject": "Thank you for subscribing",
"from_address": "my_company@example.com",
"from_name": "My Company",
"html_content": "<html><body><p>We have noticed that you recently subscribed for our newsletter<\/p><\/body><\/html>"
]
}
JSON Response
"id": 1,
"result": {
"batch_id": 456,
"list_id": 1234567,
"contact_ids": {
"0": 15,
"1": 16,
"2": 17
}
},
"error": null
}
Remarks
Transactional messages are sent to one or more (up to 100) new Contacts with the html or plain text contents provided.
Once each message is sent their results are stored within a Transactional Group report with the transactional_group
name provided.
Transactional Groups function in a similar way as reports; these reports continue to grow over time when more transactional messages are sent.
It is possible to send a text only email by providing an empty value for the html_content
and providing valid text_content
.
The following conditions apply when sending messages:
- Each Contact supplied must specify the correct email address field for the List provided. For example, if the email field name is "Primary Email", then the contact must have an "Primary Email" field as the recipient email address.
- The
from_address
must have a verified domain name before messages are sent. Domains can be verified within the Deliverability page for the Account. - When supplying secretive data in an email we recommend using wildcard (variables). If the Fields are not within
stored_field
then they are deleted after the message is sent. - The "API Upload" Campaign Event is triggered for each Contact that is successfully added or overwritten.
- The method does not trigger subscription Autoresponders or send subscription notification messages. See the subscribeContact method if you want to trigger these.
- Messages are not created after a transactional send.
Error Codes
This method may return the following error codes in addition to the standard error codes:
Code | Error | Description |
---|---|---|
303 |
Unable to Load Database | list_id is not a valid List. |
310 |
Invalid from address | from_address is not a valid email. |
310 |
Invalid email subject | email_subject is not supplied and/or valid. |
310 |
Invalid from name | from_name is not supplied and/or valid. |
310 |
Invalid Message content | Both html_content and text_content are not supplied and/or valid. |
315 |
Email List Field not found | The required email field is not available within the List. |
410 |
Unable to create transactional Batch | An internal issue has occurred when creating the Batch. |
411 |
Credit send limits exceeded | Credit send limits have been reached for your account. Please contact support for further assistance. |
412 |
The from address is not confirmed | Please ensure that the domain within the from_address is verified. |
413 |
Maximum allowed transactional groups | The account has hit or exceeded the total groups allowed. Please contact support for further assistance. |
414 |
Local file link | Urls have been found to point to local files instead of website files. ie, file://127.0.0.1/img.png |
414 |
Too many wildcard conditions | One or more wildcards have more than 75 conditionals. Reduce the total number of conditionals. |
414 |
Message exceeds size limit | After applying wildcards the message size has exceeded the limit |
414 |
Files exceed size limit | After applying wildcards the file sizes have exceeded the limit |
415 |
No valid contacts supplied | One or more contacts items have been provided without valid data. |
416 |
Maximum allowed contacts exceeded | The total count of contacts has exceeded the limit for this method. |
417 |
Unable to create stored fields | Ensure that the labels provided within stored_fields are valid Field names. |
418 |
No contacts could be saved | Contacts were unable to be saved against the List. |
419 |
One or more contacts are invalid | One or more contacts items have been provided without valid data. |
421 |
List does not have a valid Email field | Check that the List provided contains an Email Address field |