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

Parameters

*Required

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

Query string parameters

?sendTime[gt]=2018-01-01T00:00:00.000Z

?sendTime[gte]=2018-01-01T00:00:00.000Z

?sendTime[lt]=2018-01-01T00:00:00.000Z

?sendTime[lte]=2018-01-01T00:00:00.000Z

?status=paused

?triggers[api][enabled]=true

?triggers[event][enabled]=true

?triggers[recurring][enabled]=true

?tags=welcome

?mdtID=591f1a26ac0c811781bf44ea

?ct[gt]=2018-01-01T00:00:00.000Z

?ct[gte]=2018-01-01T00:00:00.000Z

?ct[lt]=2018-01-01T00:00:00.000Z

?ct[lte]=2018-01-01T00:00:00.000Z

?page=3

?per_page=100

?sort_by=sendTime

?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}

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}

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}

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

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

Parameters

*Required

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}

Query string parameters

?experiment=SubjectTest

?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

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

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

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

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.