Vision 6

sendTransactionalEmail

Send supplied email content to one or more recipients

sendTransactionalEmail

Send supplied email content to one or more recipients

Top ↑

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

$group_name = 'Transactional Messages';
$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

See Also

Method References
Popular Pages