Message and Batch Methods

Overview

This section includes both Message and Batch methods. First this page covers information necessary for using Message methods, and then it explains Batches and reviews Batch methods.

Message Types

There are two Message types: Email and SMS (text message). An Email is sent electronically over a computer network to a recipient's Email address, while an SMS Message is sent from our system to a mobile network, which delivers the Message to the recipient's mobile number.

The Message types share the Message object array shown below although some Fields are only used by one of the Message types. Email Messages have a greater number of required Fields and options because they may include update links, unsubscribe links, and various formats of text, while SMS Messages contain brief snippets of plain text.

You can use API methods to add, edit, delete, count, and search Messages. Click on any of the following Message methods to access the reference page. All of these methods apply to Email and SMS Messages.

• addMessage
• countMessages
• deleteMessage
• editMessage
• getMessageById
• getMessagesSentToContact
• searchMessages

Additional Message Categories

Email and SMS are one way the system categorises Messages. In addition the system categorises some Messages by function without distinguishing whether they are Email or SMS.

• Autoresponder - An Autoresponder contains a Message ID and a trigger action that causes the Autoresponder to send the Message. For example, when someone subscribes to your website, your Autoresponder is triggered and sends Message ID 451 to the new Subscriber.
  For more information, see Autoresponder Methods.
  
  
• Campaign Event Message - A Message triggered by an event in a Campaign. (Note: See the Help in the user interface for information about Campaigns.)
  
  
• Notification - A Message sent to alert Users or Contacts who must know when an event occurs. For example, each time a visitor sends a comment to your blog, the system sends your blog author a Notification that a message is waiting for moderation..
  
  

Two additional categories describe the way Messages are sent through the user interface. Quicksend is only used for SMS Messages.

• Manual Message - A Message sent by a User through the user interface.
  
  
• Quicksend - An SMS Message typed into a form in the user interface and immediately sent to Contacts or Lists.
  
  

What is a Batch?

Messages are sent in Batches. Initially, a Batch includes the ID of the Message you are sending and the IDs of the recipients, who are either Contacts or entire Lists of Contacts. When a Batch is added, the system sends it to a Batch Queue, where it is populated with the addresses of all of the Contacts specified as recipients. The system sends the Batch at a scheduled time or a time that is optimal considering its priority and the available resources.

Batches give you some control over Message processing. You can schedule a Batch, and while a Batch is in the send process, you can pause it, stop it, and perform other actions on it. When a Batch send is complete, you can gather statistics that show you what actions recipients took after receiving the Batch Message.

What is a Batch Queue?

You create a Batch by calling either addBatch or addBatchByContactSearch. When either method is called, the system sends the Batch information to the Batch queue. Using the Message ID and the recipient IDs, a processor populates the Batch with the recipients' Email or SMS addresses.

The queue processor knows when to populate the Batch by the value you enter in the time Field in addBatch or addBatchByContactSearch. If you enter now, the processor populates it immediately; if you enter send, the processor populates the Batch when it is at the front of the Queue and ready to be sent.

Once the Batch is in the Queue, the system gives it a Queue ID that is returned to the calling application. The Batch does not receive a Batch ID until it is populated with Contact addresses.

Getting the Batch ID

As a best practice, after adding the Batch, poll the system using getBatchIdByQueueId to get the Batch ID as soon as the Batch is populated and assigned a Batch ID. You must have the Batch ID to use editBatch to pause, unpause, cancel, or reschedule a Batch and to call get Methods to get statistics after the Batch send is completed.

Batch Send Process

The system sends the Batch at a scheduled time or, if the batch is not scheduled, at an optimal time.

Batch Methods

Methods exist for adding, editing, counting, and deleting.

• addBatch - Adds a Batch with the Message and Contacts you specify.
• addBatchByContactSearch - Adds a Batch with the Message you specify and Contacts that match your search criteria.
• countBatches - Returns the number of Batches that match your search criteria.
• deleteBatch - Deletes a Batch.
• editBatch - Changes the state of a Batch in the Queue. A list of Batch states follows.
• searchBatches - Returns Batches that match search criteria.

Batch States

Active States

1 Initialising - Currently being built by the System's Queue Processor

2 Pending - Waiting to be Sent

3 Sending - Sending in Progress

4 Completed - Completed Successfully

Inactive States

5 Failed - Failed

6 Cancelled - Cancelled by the User

7 Paused - Temporarily Stopped by the User or System

The GetBatch Methods: Monitoring a Batch and Getting Batch Statistics

A large number of getBatch methods exist for monitoring Batches in the send process and obtaining statistics about the Batches and their Contacts.

getBatchStatus and getBatchById return various statistics including the send_status Field, which stores a string specifying the Batch state. The value of send_status enables you to monitor a Batch. The possible values for send_status are listed above, under Batch States.

Another useful statistic that many Batch methods return is send_status_count, which tells the number of Contacts who have received the Message at this point.

The following table defines each of the getBatch methods used for obtaining statistics:

Causes of Batch Failure:

• All the Message sends failed.

• The Message to be sent was deleted.

• The Batch was sent to an empty List.