How can we help?

Overview

The batch messages resource sends a message or schedules a message to be sent as a one-time communication. Visit this article for information on creating and sending batch messages via UI.

Batch message API calls contain details on content, channel, send trigger, type of communication (transactional or promotional), subject line, from and reply addresses, and HTML layout.

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's placed into draft status by default. This enables editing and subsequent modifications to the message, as well as deleting the batch message.
• It's important to note that the PUT method is required to activate the sending or scheduling of the message using its ID (provided in the POST response).
  • Example: PUT/<path>/v2/batchmessages/{id}/send
  • If there's 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/v2/batchmessages call is also used to retrieve info on daily message automations sends.

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here.

Methods, parameters, and examples

• POST/v2/batchmessages
• GET/v2/batchmessages
• PUT/v2/batchmessages/{id}
• GET/v2/batchmessages/{id}
• DELETE/v2/batchmessages/{id}
• PUT/v2/batchmessages/{id}/send
• PUT/v2/batchmessages/{id}/sendtest
• GET/v2/batchmessages/{id}/renderedwip/{contactID}
• PUT/v2/batchmessages/{id}/pause
• PUT/v2/batchmessages/{id}/resume
• PUT/v2/batchmessages/{id}/cancel
• PUT/v2/batchmessages/{id}/unschedule

POST/v2/batchmessages

• Parameters
• Example JSON requests
• Example request URL

• Required

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_2025",
    "schedule": "2025-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": "InboxMonster",
        "enabled": true
    }]
}

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

https://<path>/v2/batchmessages

GET/v2/batchmessages

• Query string parameters
• Example request URLs

The following URL will retrieve all batch messages.

https://<path>/v2/batchmessages

The following URL 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.

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

PUT/v2/batchmessages/{id}

• Parameters
• Example JSON request
• Example request URL

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

{
  "status": "",
  "sendtrigger": "manual",
  "classification": "promotional",
  "name": "promo_01_20_2025",
  "schedule": "2025-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"
}

The following URL in conjunction with the JSON will perform the PUT of the batch message with the ID of 252:58ffed51f0c36063476c1752:ot.

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

GET/v2/batchmessages/{id}

The following URL will retrieve a batch message where the ID value is 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/batchmessages/252:58ffed51f0c36063476c1752:ot

DELETE/batchmessages/{id}

The following URL will delete a batch message where the ID value is 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/batchmessages/252:58ffed51f0c36063476c1752:ot

PUT/v2/batchmessages/{id}/send

The following URL perform the PUT to the batch message with the ID 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/batchmessages/252:58ffed51f0c36063476c1752:ot/send

PUT/v2/batchmessages/{id}/sendtest

• Required

Email as identifier

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

cID as identifier

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

The following URL in conjunction with the JSON will perform the PUT to the batch message with the ID 252:58ffed51f0c36063476c1752:ot.

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

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

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

• Message ID = 252:594ac3d2f0c360031181a7f0:ot
• Contact ID = 58d30719ac0c8117814da1f3

https://<path>/v2/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3

PUT/v2/batchmessages/{id}/pause

The following URL will perform the PUT to the batch message with the ID 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/batchmessages/252:58ffed51f0c36063476c1752:ot/pause

PUT/v2/batchmessages/{id}/resume

The following URL will perform the PUT to the batch message with the ID 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/batchmessages/252:58ffed51f0c36063476c1752:ot/resume

PUT/v2/batchmessages/{id}/cancel

The following URL will perform the PUT to the batch message with the ID 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/batchmessages/252:58ffed51f0c36063476c1752:ot/cancel

PUT/v2/batchmessages/{id}/unschedule

The following URL will perform the PUT to the batch message with the ID 252:58ffed51f0c36063476c1752:ot.

https://<path>/v2/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.

Have a question?

Contact support