Vision 6

sendTransactionalMessage

Send an existing Message to one or more recipients

sendTransactionalMessage

Send an existing Message to one or more recipients

Top ↑

Syntax

object sendTransactionalMessage(
    string api_key,
    string transactional_group,
    int message_id,
    int list_id,
    array contacts,
  [ 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.

message_id (int)

The ID of the Message to send.

list_id (int)

The ID of the List to add Contacts to.

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.

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';
$message_id = 5784;
$list_id    = 7654321;

$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'
  ),
);

$api = new Api($url, 'YOURAPIKEY');
$transactional_result = $api->invokeMethod('sendTransactionalMessage', $group_name, $message_id, $list_id, $contacts);

// 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": "sendTransactionalMessage",
  "params": [
      "YOURAPIKEY",
      "Transactional Messages",
      5784,
      7654321,
      [
          {
              "First Name": "Alice",
              "Email": "alice@example.com"
          },
          {
              "First Name": "Bob",
              "Email": "bob@example.com"
          },
          {
              "field_75698": "Sam",
              "field_46899": "sam@example.com"
          }
      ]
  ]
}

JSON Response

{
    "id": 1,
    "result": {
        "batch_id": 456,
        "message_id": 5784,
        "list_id": 7654321,
        "contact_ids": {
            "0": 15,
            "1": 16,
            "2": 17
        }
    },
    "error": null
}

Remarks

Transactional messages are sent to one or more (up to 100) new Contacts. 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.

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.

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.
307 Unable to Load Message message_id does not exist or does not belong to your Account.
310 Invalid from address from_address is not a valid email or mobile phone.
310 Invalid message The message provided is empty or not valid for the transactional method.
315 Email List Field not found The required email field is not available within the List.
410 Unable to create transactional Batch An 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 of 256KB
414 Files exceed size limit After applying wildcards the file sizes have exceeded the limit of 20MB
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 add 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 Check each contact has a supplied email address field that matches the list field.
420 SMS Messages are not supported This method does not support Text Messages at this time
421 List does not have a valid Email field Check that the List provided contains an Email Address field

See Also