# 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](https://support.cordial.com/hc/en-us/articles/115005363847).

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](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#getBatch) 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](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.

- [Learn more about Cordial API authentication here](httpss://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication).

## Methods, parameters, and examples

- [POST/v2/batchmessages](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#postBatch)
- [GET/v2/batchmessages](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#getBatch)
- [PUT/v2/batchmessages/{id}](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchID)
- [GET/v2/batchmessages/{id}](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#getBatchID)
- [DELETE/v2/batchmessages/{id}](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#deleteBatchID)
- [PUT/v2/batchmessages/{id}/send](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchIDSend)
- [PUT/v2/batchmessages/{id}/sendtest](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchSendTest)
- [GET/v2/batchmessages/{id}/renderedwip/{contactID}](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#getRendered)
- [PUT/v2/batchmessages/{id}/pause](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchIDPause)
- [PUT/v2/batchmessages/{id}/resume](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchIDResume)
- [PUT/v2/batchmessages/{id}/cancel](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchIDCancel)
- [PUT/v2/batchmessages/{id}/unschedule](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#putBatchIDUnschedule)

### POST/v2/batchmessages

| Method | URL Path |
| --- | --- |
| POST | /v2/batchmessages |
| - Creates a batch message template in the Cordial database using the appropriate JSON body.<br>- 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](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-1-0)
- [Example JSON requests](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-1-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-1-2)

* Required

| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| ### Message send information |
| * 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_2025 |
| 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. | 2025-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**.<br>**Possible Values:**<br>enabled, disabled |
| ### Message header |
| * 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. | InboxMonster |
| enabled | Boolean | Flag to determine if the test is enabled or disabled. The default is **disabled**. | true |

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

| Method | URL Path |
| --- | --- |
| GET | /v2/batchmessages |
| - Retrieves all batch messages from the Cordial database.<br>- Note: Info and stats on daily message automations is retrieved using this API call. You can filter the response for message automations using the triggers parameter, the creation time, or mdtID. |

- [Query string parameters](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-2-0)
- [Example request URLs](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-2-1)

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

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}

| Method | URL Path |
| --- | --- |
| PUT | /v2/batchmessages/{id} |
| - Updates an unsent batch message in the Cordial database using the appropriate JSON body.<br>- The batch message's record is defined by the batch messages's unique ID value (generated by the POST method).<br>- The PUT method can only be used if the message status is Draft. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-3-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-3-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570697-Batch-messages-API#zp-3-2)

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}

| Method | URL Path |
| --- | --- |
| GET | /v2/batchmessages/{id} |
| - Retrieves a batch message from the Cordial database.<br>- The batch message's record is defined by the batch message's unique ID value. |

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}

| Method | URL Path |
| --- | --- |
| DELETE | /v2/batchmessages/{id} |
| - Deletes a batch message within the Cordial database.<br>- The batch message is defined by the batch message's unique ID value. |

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

| Method | URL Path |
| --- | --- |
| PUT | /batchmessages/{id}/send |
| - Sends or schedules a batch message within the Cordial database.<br>- The batch message record is defined by the batch message's unique ID value. |

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

| Method | URL Path |
| --- | --- |
| PUT | /batchmessages/{id}/sendtest |
| - Sends a test batch message.<br>- The batchmessages record is defined by the batchmessages's unique ID value. |

* 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" ] |

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

| Method | URL Path |
| --- | --- |
| GET | /v2/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.<br>- The batch message's record is defined by the batch message's unique ID value.<br>- The contact record is defined by the contact's unique cID value. |

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

| Method | URL Path |
| --- | --- |
| PUT | /v2/batchmessages/{id}/pause |
| - Pauses the sending of a batch message.<br>- The batch message record is defined by the batch message's unique ID value. |

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

| Method | URL Path |
| --- | --- |
| PUT | /v2/batchmessages/{id}/resume |
| - Resumes the sending of a batch message.<br>- The batch message record is defined by the batch message's unique ID value. |

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

| Method | URL Path |
| --- | --- |
| PUT | /v2/batchmessages/{id}/cancel |
| - Cancels the sending of a batch message. A paused message may also be canceled.<br>- The batch message record is defined by the batch message's unique "id" value. |

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

| Method | URL Path |
| --- | --- |
| PUT | /v2/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).<br>- The batch message record is defined by the batch message's unique ID value. |

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](https://support.cordial.com/hc/en-us/articles/4402427843597-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. |
| 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: {} does not exist. | The given audience was not found. |

### Have a question?

[Contact support](https://support.cordial.com/hc/en-us/requests/new)