How can we help?

Search

Batch messages API

Overview

The Batch Messages resource sends a message, or schedules a message to be sent, as a one-time communication. It contains details on content, channel, send trigger, type of communication (transactional or promotional), subject line, from and reply addresses, and HTML.

Additional information

  • When creating a batch message, you have the option to send it on command, or to queue it for a later date and time.
  • Sending is a two part process that involves a POST method to create the message and a PUT method to schedule or send the message.
  • When a batch message is created via the POST method, it is  placed into a "draft" status by default. This enables editing and subsequent modifications to the message, as well as deleting the batch message.
  • It is important to note that the PUT method is required to activate the sending or scheduling of the message using its "id" (provided back in the response of the POST).
    • Example: PUT <path>/batchmessages/{id}/send'
    • If there is a "schedule" date, then the "status" changes to "scheduled"'
    • If there is no "schedule" date, then the message is immediately queued and the "status" is changed to "pending".
    • In either case, as soon as sending begins, the "status" will change to "processing" and then to "sent" once complete.
  • The GET /batchmessages call is also used to retrieve info on daily Automation sends.

Methods, parameters, and examples

POST/batchmessages

Method URI Path
POST /batchmessages
Creates a batch message template in the Cordial database using the appropriate JSON body.

Posting more than one time will cause subsequent batch messages to be created. Use PUT to change or update a batch message that has not yet sent.

Parameters

*Required

Parameter Type Description Example
MessageSend
*channel string Messaging channel key (e.g. email, sms, push). Note that some of your channels may have custom keys. email
*classification string If applicable, classifies the message as transactional or promotional. transactional
name string An optional name given to the message. Jan_Newsletter_2018
tags array An array of string values to identify and categorize the message. Tags are case sensitive. ["birthday","promo"]
audience-key string Defines a saved audience rule "name". 30_day_engaged
schedule date An optional date and time at which the message is to be sent. The date should be in the future and use the ISO 8601 format. 2018-01-09T22:47:12+0000
scheduleType string Enable sending at the scheduled time per the time zone of the contact. If not specified, the template will send using the Cordial account default time zone. contactTZ
transportID string Defines the transportID if overriding the default. Default is used if this parameter is not included. 57d098b66c8766fd53ad19d7
trackLinks string Determines if link performance will be tracked. Default is enabled.
Possible Values:
enabled, disabled		 enabled
Message/Headers
*subject string The subject line for the communication. Welcome to myco!
*fromEmail string The email address that the message is from. email@myco.io
*fromDesc string Describes the sender. CS Dept
*replyEmail string The email address that the message's replies will go to. email@example.com
Message/Content
*text/html string HTML markup for the message. <div>content</div>
tests (array)
type String Defines the test to be run. 250ok
enabled Boolean Flag to determine if the test is enabled or disabled. The default is disabled. true

Example JSON requests

The following will create and schedule a new batch message for a promotional email to all contacts using the default transport. The response will include an "id" for the newly created batchmessages instance.

{
	"sendtrigger": "manual",
        "channel": "email",
	"classification": "promotional",
	"name": "promo_01_20_2018",
	"schedule": "2018-01-2316:10:08",
	"scheduleType": "contactTZ",
	"message": {
		"headers": {
			"subject": "Buyoneticketandgetsecondhalfprice",
			"fromEmail": "skiguy@example.com",
			"replyEmail": "skiguy@example.com",
			"fromDesc": "SkiPromotionsTeam"
		},
		"content": {
			"text/html": "<div>Some Content</div>"
		}
	},
	"transportID": "57d098b66c8766fd53ad19d7",
	"trackLinks": "enabled",
	"tests": [{
		"type": "250ok",
		"enabled": true
	}]
}

Example request URI

The following URI in conjunction with the JSON will perform the POST of batchmessages.

http://<path>/batchmessages

GET /batchmessages

Method URI Path
GET /batchmessages

Retrieves all batch messages from the Cordial database.

Note that info and stats on daily Automation sends is retrieved using the GET /batchmessages call. You are able to filter the response for automation sends using the triggers parameter, the creation time or mdtID.

Query string parameters

Parameter Type Description Example
sendTime[gt] string Returns records where the send time is greater than the specified date. 
?sendTime[gt]=2018-01-01T00:00:00.000Z
sendTime[gte] string Returns records where the send time is greater than or equal to the specified date. 
?sendTime[gte]=2018-01-01T00:00:00.000Z
sendTime[lt] string Returns records where the send time is less than the specified date. 
?sendTime[lt]=2018-01-01T00:00:00.000Z
sendTime[lte] string Returns records where the send time is less than or equal to the specified date. 
?sendTime[lte]=2018-01-01T00:00:00.000Z
status string The message status.
Possible Values:
sent, cancelled, paused, sending		 
?status=paused
triggers[api][enabled] string For Automation sends: filters results based on whether the API trigger is enabled or disabled.
Possible Values:
true, false		 
?triggers[api][enabled]=true
triggers[event][enabled] string For Automation sends: filters results based on whether the event trigger is enabled or disabled.
Possible Values:
true, false		 
?triggers[event][enabled]=true
triggers[recurring][enabled] string For Automation sends: filters results based on whether the recurring trigger is enabled or disabled.
Possible Values:
true, false		 
?triggers[recurring][enabled]=true
tags string Returns results that contain the specified message tags. 
?tags=welcome
mdtID string The automation template ID. 
?mdtID=591f1a26ac0c811781bf44ea
ct[gt] string Returns records where the  create date is greater than the specified date. 
?ct[gt]=2018-01-01T00:00:00.000Z
ct[gte] string Returns records where the create date is greater than or equal to the specified date. 
?ct[gte]=2018-01-01T00:00:00.000Z
ct[lt] string Returns records where the create date is less than the specified date. 
?ct[lt]=2018-01-01T00:00:00.000Z
ct[lte] string Returns records where the create date is less than or equal to the specified date. 
?ct[lte]=2018-01-01T00:00:00.000Z
page string Specifies the results page number to be returned. 
?page=3
per_page string Specifies the number of records returned per page. 
?per_page=100
sort_by string Specifies the field to sort by. 
?sort_by=sendTime
sort_dir string Specifies the sort direction as ascending or descending. 
Possible Values:
desc, asc		 
?sort_dir=desc

Example request URIs

The following URI will retrieve all batch messages.

http://<path>/batchmessages

The following URI will retrieve all batch messages, starting from the third page and grouping messages by 10. For example, page-1 would have included the first 10, page-2 the second group of 10 and so on.

http://<path>/batchmessages?page=3&per_page=10

PUT /batchmessages/{id}

Method URI Path
PUT /batchmessages/{id}
Updates an unsent batch message in the Cordial database using the appropriate JSON body.

The batch message's record is defined by the batch messages's unique "id" value (generated by the POST method).

The PUT method can only be used if the "status" is "draft".

Parameters

See the parameters for POST/batchmessages above.

Example JSON requests

The following will change the "subject" and push the launch "schedule" date by one day.

{
  "status": "",
  "sendtrigger": "manual",
  "classification": "promotional",
  "name": "promo_01_20_2018",
  "schedule": "2018-01-24 16:10:08",
  "scheduleType": "contactTZ",
  "message": {
    "headers": {
      "subject": "Buy one ticket and get the second half price",
      "fromEmail": "skiguy@example.com",
      "replyEmail": "skiguy@example.com",
      "fromDesc": "Ski Promotions Team"
    },
    "content": {
      "text/html": "<div>Some Content</div>"
    }
  },
  "transportID": "account transportID",
  "trackLinks": "enabled"
}

Example request URI

The following URI in conjunction with the JSON will perform the PUT of the batch message with the "id" of "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot

GET /batchmessages/{id}

Method URI Path
GET /batchmessages/{id}
Retrieves a batch message from the Cordial database.

The batch message's record is defined by the batch message's unique "id" value.

Example request URI

The following URI will retrieve a batch message where the "id" value is "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot

DELETE /batchmessages/{id}

Method URI Path
DELETE /batchmessages/{id}
Deletes a batch message within the Cordial database.

The batch message is defined by the batch messages's unique "id" value.

Example request URI

The following URI will delete a batch message where the "id" value is "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot

PUT /batchmessages/{id}/send

Method URI Path
PUT /batchmessages/{id}/send
Sends or schedules a batch message within the Cordial database.

The batch message record is defined by the batch message's unique "id" value.

Example request URI

The following URI perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/send

PUT /batchmessages/{id}/sendtest

Method URI Path
PUT /batchmessages/{id}/sendtest
Sends a test batch message.

The batchmessages record is defined by the batchmessages's unique "id" value.

Parameters

*Required

Parameter Type Description Example
*contact identifier array An array of contact identifier values to receive the test message. [ "test1@example.com","test2@example.com" ]

Example JSON requests

  • {
  "email": [
    "test1@example.com","test2@example.com"
  ]
}

  • {
  "cID": [
 "58d30719ac0c8117814da1f3","39f67345aq0c0276295da1g9"
  ]
}

  • {
  "customKey": [
    "identifierValue1","identifierValue2"
  ]
}

Example request URI

The following URI in conjunction with the JSON will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/sendtest

GET /batchmessages/{id}/renderedwip/{contactID}

Method URI Path
GET /batchmessages/{id}/renderedwip/{contactID}

Retrieves the message headers, the rendered HTML, and the experiment name and variants of a batch message draft for a specified contact from the Cordial database.
The batch message's record is defined by the batch message's unique "id" value.
The contact record is defined by the contact's unique "cID" value.

Query string parameters

Parameter Type Description Example
experiment string Name of experiment. 
?experiment=SubjectTest
variant string Variant name. 
?variant=Test1

Example request URIs

The following URI will perform the GET to the batch message where:

  • Message ID = 252:594ac3d2f0c360031181a7f0:ot
  • Contact ID = 58d30719ac0c8117814da1f3
http://<path>/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3

The following URI will perform the GET to the batch message where:

  • Message ID = 252:594ac3d2f0c360031181a7f0:ot
  • Contact ID = 58d30719ac0c8117814da1f3
  • Subject experiment = SubjectTest
  • Subject experiment Variant = Test1
http://<path>/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=Test1

The following URI will perform the GET to the batch message where:

  • Message ID = 252:594ac3d2f0c360031181a7f0:ot
  • Contact ID = 58d30719ac0c8117814da1f3
  • Subject experiment = SubjectTest
  • Subject experiment Variant = Test1
  • Body experiment = AB-No-Champ
  • Body experiment variant = B
http://<path>/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=Test1&experiment=AB-No-Champ&variant=B

PUT /batchmessages/{id}/pause

Method URI Path
PUT /batchmessages/{id}/pause
Pauses the sending of a batch message.

The batch message record is defined by the batch message's unique "id" value.

Example request URI

The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/pause

PUT /batchmessages/{id}/resume

Method URI Path
PUT /batchmessages/{id}/resume
Resumes the sending of a batch message.

The batch message record is defined by the batch message's unique "id" value.

Example request URI

The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/resume

PUT /batchmessages/{id}/cancel

Method URI Path
PUT /batchmessages/{id}/cancel
Cancels the sending of a batch message. A paused message may also be canceled.

The batch message record is defined by the batch message's unique "id" value.

Example request URI

The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/cancel

PUT /batchmessages/{id}/unschedule

Method URI Path
PUT /batchmessages/{id}/unschedule
Unschedule a scheduled batch message. Unscheduled messages will revert to draft status and can be edited. Messages that are in the processing status cannot be unscheduled ("Unable to unschedule message" notification will be returned).

The batch message record is defined by the batch message's unique "id" value.

Example request URI

The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".

http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/unschedule

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Batch Messages API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API error responses page.

errorKey Message Modifications
CHANNELS_KEY_NOT_FOUND Incorrect channel for current account The provided channel is not present for the current account.
CHANNELS_KEY_NOT_FOUND Channel is not detected Check that the messaging channel key was input correctly.
BATCH_MESSAGES_SMS_TRANSACTIONAL_MESSAGES_NOT_ALLOWED Transactional messages are not allowed for messages of type sms. SMS messages must be classified as promotional.
BATCH_MESSAGES_AUDIENCE_FILTER_CONFLICT Please use only one from existing filters 'audience' OR 'audience-key' Either audience or audience-key may be used to filter, but not both.
MESSAGE_TRANSPORT_NOT_CONFIGURED Transport must be configured before messages can be created Ensure the transport has been configured and input correctly.
BATCH_MESSAGES_AUDIENCE_NOT_FOUND Audience with name: ':audienceKey' does not exist. The given audience was not found.
BATCH_MESSAGES_TEST_INTEGRATION_DISABLED Integrations is disabled The integration setting has been set to disabled.
BATCH_MESSAGES_INSUFFICIENT_TEST_PARAMETERS Not enough parameters for tests Check that both Tests parameters are correctly filled in.
BATCH_MESSAGES_TEST_INTEGRATION_ERROR Error data from 250OK integration Check the integration data.
BATCH_MESSAGES_CANNOT_EDIT_SENT_MESSAGE Can't be changed A sent message cannot be edited.
MESSAGE_TRANSPORT_NOT_SELECTED Transport should be selected before sending Ensure the transport has been selected properly.
BATCH_MESSAGES_REMOVE_REQUEST_NOT_ALLOWED It's not allowed to remove this message. This message is not allowed to be removed.
BATCH_MESSAGES_CANNOT_UPDATE_STATUS_TO_SCHEDULED Batch messages cannot update status to scheduled. Messages that are in the processing status cannot be scheduled.
BATCH_MESSAGES_CANNOT_UPDATE_STATUS_TO_PENDING Batch messages cannot update status to pending. A sent message cannot be changed to pending status.
EXPERIMENT_VALIDATION_ERROR Incorrect experiment name
Supported experiment strategies in this context are split,split-with-champion
dissimilar experiments		 Check that the experiment names are correct.
BATCH_MESSAGES_UNABLE_TO_UPDATE_JOB No sub jobs created
Could not create SendBatchMessage job		 This job was unable to be updated.
RECORD_NOT_FOUND Batch Message does not exist
Message ID is not found.		 The identifier entered didn't return any results.
BATCH_MESSAGES_CONTACT_KEY_MUST_BE_INDEXED Key :mainIdentifier not indexed field. All contacts should be indexed.
BATCH_MESSAGES_CONTACT_NOT_ASSOCIATED_WITH_CHANNEL Contact does not support message channel.
Contact doesn't have a valid entry for :name channel		 Ensure the contact information has been input correctly for this channel.
BATCH_MESSAGES_CONTACT_NOT_ASSOCIATED_WITH_CHANNEL Message is stopped
No msID available
Invalid contact		 Ensure the contact information has been input correctly for this channel.
BATCH_MESSAGES_SEND_RENDER_ERROR Unable to render content :message This is a render error using Smarty.
BATCH_MESSAGES_SEND_INTERNAL_RENDER_ERROR Internal render error Contact your Cordial support member as soon as possible to resolve this issue.
BATCH_MESSAGES_UNABLE_TO_ASSIGN_MCID Error assigning message to contact Ensure the contact information has been input correctly for this message.
BATCH_MESSAGES_CONTACT_NOT_FOUND Contact does not exist
Contact is not found.		 The contact identifier entered didn't return any results.
BATCH_MESSAGES_STATUS_ERROR Message canceled and can't be resumed
Message already canceled		 The message status does not allow updates.
BATCH_MESSAGES_CUSTOM_KEY_ERROR Unable to determine a channel
Unable to determine a channelType by channel :channel		 Ensure channel is input correctly.
BATCH_MESSAGES_SCHEDULE_ERROR Time is in the past.
sendSchedule is required		 Check that the time has been scheduled for a future time.
CHANNEL_NOT_FOUND Service for this channel not exist Service for this channel does not exist.
BATCH_MESSAGES_MISSING_AUDIENCE_INCLUDE_RULE Audience rule is invalid. {include} should not be empty Check that the include is valid and has been input correctly.
MESSAGE_TRANSPORT_INVALID_ACCOUNT_TRANSPORT TransportID does not belong to this account The selected transport is not valid for this account.
BATCH_MESSAGES_TEST_ERROR Not enough parameters Check the required parameters for correct formatting.
BATCH_MESSAGES_CANNOT_UNSCHEDULE_PROCESSING_MESSAGE Unable to unschedule message Batch messages with the status of 'Processing' cannot be unscheduled.
BATCH_MESSAGES_INCORRECT_AUDIENCE_RULE Incorrect audience rule Make sure the audience rule was input correctly.
CONTACT_DATA_NOT_FOUND Contact not provided in payload Some contact data may be missing.
NO_ADDRESS_SET Address not present in contact for particular message channel The contact's address may be missing for this channel.
INVALID Contact marked as invalid The contact's information may be missing/incorrect.
NOT_SUBSCRIBED Contact not subscribed The contact must be subscribed to receive messages.
EXCEEDED_RATE_LIMIT Duplicated record in message contacts collection Contact your Cordial support member as soon as possible to resolve this issue.
INTERNAL_ERROR Internal error Contact your Cordial support member as soon as possible to resolve this issue.

Comments

0 comments

Please sign in to leave a comment.