Send Transactional Messages Using Automated Message Rules And The API

About this task

Note: This is not the optimal way to send transactional messages if you are using API version 4. If you are using API version 4, we suggest you follow the instructions for Send Transactional Messages Using The API.

To send transactional messages using automated message rules:

Procedure

  1. Create an email message in the application.
    This email message acts as a template for the transactional email. The data relevant to the contact receiving the email is passed in using field tags (%%field%%), special tags (%%!field%%), API message tags (%%#field%%), and/or loop tags (%%#data_#%%).

    If you plan on asking the contact to opt-in to marketing communication, the message should include a manage preferences link. If you are using a previously sent email, or if you wish to make a test delivery prior to using the email as a transactional message with the API, the application assumes the message is a bulk/marketing email and automatically appends an unsubscribe link.

    To remove this link, re-save the message in the application prior to using the email for transactional deliveries. This removes any automatically appended links until the next delivery from inside the application.
    Note: After the email is re-saved, the unsubscribe link will continue to appear in the message preview but will not be included when the message is sent.
    For more information on creating email messages, see Creating an Email Message Using the WYSIWYG Editor. For more information on each type of tag that can be used in transactional messages, see the following help topics:

    Example use of API message tags

    Example content passed in from the API after the message is sent

  2. Request transactional approval for the email message.
    For more information on getting an email message approved for transactional sending, see Request Transactional Message Approval.
  3. Go to Automation > Automated Message Rules.
  4. Click Create New Automated Message Rule.
  5. Type a name for the automated message rule in the text box.
  6. Click the API Triggered radio button in the Automated Message Rule Type settings.
  7. Click Next Step.
  8. Click Allow API to select sending options or Specify sending options to select where the From Name, From Address, Reply address and frequency caps are set.
  9. Click Pick Message to select the message that will be sent as part of the automated message rule.
  10. Click Verify Settings.
  11. Click Save As Draft or Save And Activate.
    The automated message rule will not be able to send email until you activate it. Clicking Save As Draft allows you to activate the automated message rule at a later date, whereas clicking Save And Activate immediately activates the automated message rule.

    You will be taken to the Overview page for the automated messages rule. You should make note of the sections called out in the image below when you get to the overview page.

    Tip: You can also get to the Overview page for an automated message rule by going to Automation > Automated Message Rules and clicking on the name of an automated message rule.
  12. Make an API call to send the transactional message you created in step 1, via the API triggered automated message rule you setup in the previous steps.
    The example script below will obtain the ID for a contact, the ID for an email message, the ID for an automated message rule, and then use those IDs to send a transactional email to the contact via the automated message rule.
     /**
     * This script will add a delivery using an API triggered
     * automated message rule. It will obtain the ID of the automated
     * message rule and the message sent via the automated message rule.
     * It will use these IDs in the addDeliveries call to send the appropriate
     * message via the appropriate API triggered automated message rule.
     *
     * @copyright  Copyright (c) 2012 Bronto Software (http://www.bronto.com)
     */
    
    $client = new SoapClient('https://xrefpi.bronto.com/v4?wsdl', array(
        'trace' => 1,
        'features' => SOAP_SINGLE_ELEMENT_ARRAYS
    ));
    setlocale(LC_ALL, 'en_US');
    
    try {
        // Add API token here
        $token = "YOUR_TOKEN_HERE";
        
        print "logging in\n";
        $sessionId = $client->login(array(
            'apiToken' => $token
        ))->return;
        
        $session_header = new SoapHeader("http://xrefpi.bronto.com/v4", 'sessionHeader', array(
            'sessionId' => $sessionId
        ));
        $client->__setSoapHeaders(array(
            $session_header
        ));
        
        // Get the id of the automated message rule you wish to send.
        // It would be more efficient to hard-code the ID here, and
        // you may choose to do that based on your own usage
        // scenario(s). The ID of the message sent via this rule will
        // be returned as part of the messageRuleObject.
        
        $messageRuleFilter = array(
            'name' => array(
                'operator' => 'EqualTo',
                'value' => 'API TRIGGERED AUTOMATED MESSAGE RULE NAME'
            )
        );
        $amr               = $client->readMessageRules(array(
            'pageNumber' => 1,
            'filter' => $messageRuleFilter
        ))->return[0];
        if (!$amr) {
            print "There was an error retrieving your automated message rule.\n";
            exit;
        }
        
        // Get the id of the contact you will be sending to. It would be
        // more efficient to hard-code the ID here, and you may choose to do that
        // based on your own usage scenario(s).
        $contactFilter = array(
            'email' => array(
                'operator' => 'EqualTo',
                'value' => 'CONTACT NAME HERE'
            )
        );
        $contact       = $client->readContacts(array(
            'pageNumber' => 1,
            'includeLists' => false,
            'filter' => $contactFilter
        ))->return[0];
        if (!$contact) {
            print "There was an error retrieving your contact.\n";
            exit;
        }
        
        // Make the delivery start timestamp. For this example,
        // we will send the delivery now.
        $now = date('c');
        
        $recipientObject = array(
            'type' => 'contact',
            'id' => $contact->id
        );
        
        // Be sure to change the generic fromName and fromEmail
        // used below!
        $delivery = array(
            'start' => $now,
            'messageId' => $amr->messageId,
            'messageRuleId' => $amr->id,
            'fromName' => 'API Robot',
            'fromEmail' => 'api_robot@example.com',
            'recipients' => array(
                $recipientObject
            )
        );
        
        $res = $client->addDeliveries(array(
            $delivery
        ))->return;
        if ($res->errors) {
            print "There was a problem scheduling your delivery:\n";
            print $res->results[$res->errors[0]]->errorString . "\n";
        } else {
            print "Delivery has been scheduled.  Id: " . $res->results[0]->id . "\n";
            print "The Delivery was sent via the following API triggered automated message rule: " . $amr->name . "\n";
        }
    }
    catch (Exception $e) {
        print "uncaught exception\n";
        print_r($e);
    }
    

    In order to make API calls, you will need an API token. For more information on creating API tokens, see Set Up/Edit SOAP API Access Tokens.

    Tip: To view an example use off addDeliveries where API message tags and loop tags are used, see API Message Tags and API Loop Tags.
    Tip: The following functions were used in the above code example. Click on the names to read more information about each API call.