Campaign Manager
Overview
This page describes the resources that make up the Campaign Manager REST API v1 it is intended for developers who want to integrate a data source directly into the Campaign Manager application.
The Campaign Manager REST API provides access to resources (data entities) via URI paths. To use this API, your application will make an HTTP request and parse the response. The response format is JSON.
Authentication
HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.
Your Campaign Manager API credentials are the same as used to login. Navigate to the Campaign Manager application under ‘Send Messages’, and view the ‘API Info’ tab to obtain your API details.
If you don’t have these details, please contact optussd@modicagroup.com .
Base URI
All API access is over HTTPS, and accessed from:
https://api.sms.optus.com.au/rest/campaign_manager/v1
Versions
The Campaign Manager API version is currently v1.
OpenAPI Specification
The OpenAPI (Swagger) specification can be found here: https://api.sms.optus.com.au/rest/campaign_manager/v1/swagger.json.
You can see code examples and further information here.
Limits and Defaults
The following limits and defaults apply for all resources:
-
Mobile number format must be in international format eg:
+61421234567. -
A maximum of 1 million members is currently supported.
-
Time of Day Restrictions can be used to limit when campaigns may send, and will apply to all campaigns sent via API. The Sending Hours User Guide details how to setup Time of Day Restrictions.
Campaigns
Scheduling a Campaign
On success:
HTTP/1.1 201 Created
Location: https://api.sms.optus.com.au/rest/campaign_manager/v1
Submit a POST request using the following attributes to schedule a broadcast:
| FIELD | DESCRIPTION | TYPE | SUB TYPE | REQUIRED |
|---|---|---|---|---|
| name | Name of the List | string | yes | |
| schedule | Scheduled start time of the campaign | string | RFC3339 timestamp | yes |
| content | Content of the text message (only required if template is not set) | string | no | |
| template | Template id to invoke a template. Uses the template text as the content of the message (only required if content is not set) | string | no | |
| mask | Source Mask | string | no | |
| batch | Free text reference | string | no | |
| Send replies to this email address | string | no | ||
| reply_response | Automatic reply sent when a text is received | string | no | |
| opt_out_response | Automatic reply sent when an Opt-Out text is received | string | no | |
| members | List of members (destinations) to send the content to | list | member | yes |
| remove_opt_outs | Remove Opt-Outs from previous campaigns - Defaults to True | boolean | no | |
| strict_validation | If the set this flag to false, any invalid lines in the request will be ignored and the campaign will be scheduled. If there are ignored lines the response will report back on the mobile numbers ignored. e.g. {"error_messages":"Failed validation for +235456456445445, ignored." Failed validation for +11, ignored. ","id":126002} If set to true the request will not be scheduled. True is the default if this field is not included. |
boolean | no |
Static Campaign Example
{
"name" : "Campaign Name",
"schedule" : "2023-07-20T09:00:00+12:00",
"content" : "Hi there!",
"members" : [
{ "destination" : "+614123123123" },
{ "destination" : "+614123123122" },
{ "destination" : "+614123123121" },
{ "destination" : "+614123123120" }
]
}
This will schedule and send the verbatim content to all members in the members list. To insert variable content (using parameters), see below.
Customise content using parameters
To customise content per recipient, the ‘members’ field will need to contain the parameters you wish to substitute in the content:
| FIELD | DESCRIPTION | TYPE | REQUIRED |
|---|---|---|---|
| destination | The mobile number to send the content to | string | yes |
| param1 | Substitution parameter to include within the content | string | no |
| param2 | Substitution parameter to include within the content | string | no |
| param3 | Substitution parameter to include within the content | string | no |
| param4 | Substitution parameter to include within the content | string | no |
| param5 | Substitution parameter to include within the content | string | no |
| param6 | Substitution parameter to include within the content | string | no |
Dynamic Campaign Example
```json { "name" : "Campaign Name", "schedule" : "2023-07-20T09:00:00+12:00", "content" : "Hi there %%1%%!", "members" : [ { "destination" : "+614123123123", "param1" : "Bob" }, { "destination" : "+614123123122", "param1" : "Sarah" }, { "destination" : "+614123123121", "param1" : "Tyler" }, { "destination" : "+614123123120", "param1" : "Paul" } ] } ```This will schedule and send the variable content (including parameter 1 in this example) personalised to all recipients in the members list containing that parameter.
Lists
Uploading a List
To create a list perform a POST to the following URI:
https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/lists
On success:
HTTP/1.1 201 List Created
Location: https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/lists/{list_id}
Note: The List ID that is returned should be stored in your database in order to delete a list in the future.
Submit a POST request using the following attributes to load a list:
| FIELD | DESCRIPTION | TYPE | SUB TYPE | REQUIRED |
|---|---|---|---|---|
| name | Name of the List | string | Yes | |
| batch | Free text reference | string | No | |
| Send replies to this email address | string | No | ||
| members | List of members (destinations) to send the content to | list | member | Yes |
| remove_opt_outs | Remove Opt-Outs from previous campaigns - Defaults to True | boolean | No | |
| strict_validation | If the set this flag to false, any invalid lines in the request will be ignored and the list will be loaded. If there are ignored lines the response will report back on the mobile numbers ignored. e.g. {“error_messages”:“Failed validation for +235456456445445, ignored. Failed validation for +11, ignored. “,“id”:126002} If set to true the request will not be loaded. True is the default if this field is not included. | boolean | No |
List creation example
{
"name" : "List Name",
"members" : [
{ "destination" : "+614123123123" },
{ "destination" : "+614123123122" },
{ "destination" : "+614123123121" },
{ "destination" : "+614123123120" }
]
}
List creation with parameters
To generate a POST request including parameters, the ‘members’ field will need to contain the parameters you want in the content:
| FIELD | DESCRIPTION | TYPE | REQUIRED |
|---|---|---|---|
| destination | The mobile number to send the content to | string | yes |
| param1 | Substitution parameter to include within the content | string | no |
| param2 | Substitution parameter to include within the content | string | no |
| param3 | Substitution parameter to include within the content | string | no |
| param4 | Substitution parameter to include within the content | string | no |
| param5 | Substitution parameter to include within the content | string | no |
| param6 | Substitution parameter to include within the content | string | no |
List creation with parameters
{
"name" : "List Name",
"members" : [
{ "destination" : "+614123123123", "param1" : "Bob" },
{ "destination" : "+614123123122", "param1" : "Sarah" },
{ "destination" : "+614123123121", "param1" : "Tyler" },
{ "destination" : "+614123123120", "param1" : "Paul" }
]
}
DELETE a List
Submit a HTTP DELETE request using the following form to delete a list:
https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/lists/{list_id}
On success:
HTTP/1.1 204 List Deleted
Deleting Multiple Lists
Submit a HTTP POST request using the following form to delete multiple lists:
https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/delete_multiple_lists
Use the following attribute in the request body:
| FIELD | DESCRIPTION | TYPE | SUB TYPE | REQUIRED |
|---|---|---|---|---|
| list_ids | List of IDs to be deleted | array | integer | Yes |
Deleting multiple lists example
{
"list_ids" : [
1234, 3456, 5678
]
}
On success, the following response is returned:
HTTP/1.1 200
{"list_ids":[1234, 3456, 5678],"message":"Deleted list ids"}
Note: if not all lists can be deleted, the request is still considered successful, and the response will only include the deleted list IDs.
GET all Lists
Submit a HTTP GET request using the following form to get all lists associated to a campaign application.
https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/lists
On success:
HTTP/1.1 200 OK
[
{
"created":"2019-10-04T10:12:19.011Z",
"id":123456,
"name":"string",
"members":[
{
"destination":"+123456789",
"param1":"string",
"param2":"string",
"param3":"string",
"param4":"string",
"param5":"string",
"param6":"string"
},
{
"destination":"+123456789",
"param1":"string",
"param2":"string",
"param3":"string",
"param4":"string",
"param5":"string",
"param6":"string"
}
]
}
]
Report
GET a report summary
Issue an HTTP GET request to the following URL to access a report for a given campaign:
https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/{campaign_id}/report
On success:
HTTP/1.1 200 OK
[
{
"list_name":"string",
"message_id":123456789,
"mobile":"+64123456",
"sent_date":"2019-02-19 15:48:01.894677",
"status":"received",
"status_date":"2019-02-19 15:48:03.498389",
"timezone":"Pacific/Auckland"
},
{
"list_name":"string",
"message_id":123456789,
"mobile":"+6412345678",
"sent_date":"2019-02-19 15:48:01.744065",
"status":"failed",
"status_date":"2019-02-19 15:48:03.192748",
"timezone":"Pacific/Auckland"
}
]
Templates
GET all Templates
Submit a HTTP GET request to the following URL get all templates associated to a campaign application.
https://api.sms.optus.com.au/rest/campaign_manager/v1/{application_name}/templates
On success:
HTTP/1.1 200 OK
[
{
"id":123,
"name":"template_name"
}
]
Error Codes
The following errors can occur:
Code |
Description |
|---|---|
| 401 - Unauthorised | Incorrect username and/or password |
| 403 - Forbidden | Not allowed access to the application, or, not allowed access to campaign manager |
| 404 - Not Found | URL is incorrect |
| 422 - Unprocessable Entity | Validation errors within the data |
| 4xx - | Something else is wrong with the request |
| 5xx - | Something is wrong with the service |
Sample error:
{
"code" : 401,
"message" : "unauthenticated for invalid credentials"
}
API List Loading
This page describes the resources that make up the Campaign Manager REST API v1 for loading lists it is intended for developers who want to integrate a data source directly into the Campaign Manager application.
The Mobile Gateway REST API provides access to resources (data entities) via URI paths. To use this API, your application will make an HTTP request and parse the response. The response format is JSON.
Authentication
HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.
Your Campaign Manager API credentials are the same as used to login. Navigate to the Campaign Manager application under ‘Send Messages’, and view the ‘API Info’ tab to obtain your API details.
If you don’t have these details, please contact optussd@modicagroup.com.
Base URI
All API access is over HTTPS, and accessed from
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/lists
Versions
The Campaign Manager API version is currently v1.
Uploading a List
On success:
HTTP/1.1 201 List Created
Location: https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/lists/list_id
Note: The List ID that is returned should be stored in your database in order to delete a list in the future.
Submit a POST request using the following attributes to load a list:
| FIELD | DESCRIPTION | TYPE | SUB TYPE | REQUIRED |
|---|---|---|---|---|
| name | Name of the List | string | Yes | |
| batch | Free text reference | string | No | |
| Send replies to this email address | string | No | ||
| members | List of members (destinations) to send the content to | list | member | Yes |
| remove_opt_outs | Remove Opt-Outs from previous campaigns - Defaults to True | boolean | No | |
| strict_validation | If the set this flag to false, any invalid lines in the request will be ignored and the list will be loaded. If there are ignored lines the response will report back on the mobile numbers ignored. e.g. {“error_messages”:“Failed validation for +235456456445445, ignored. Failed validation for +11, ignored. “,“id”:126002} If set to true the request will not be loaded. True is the default if this field is not included. | boolean | No |
Mobile number format must be international format e.g. +61421234567.
A maximum of 1 million members is currently supported.
For demonstrative purposes only:
{
"name" : "List Name",
"members" : [
{ "destination" : "+614123123123" },
{ "destination" : "+614123123122" },
{ "destination" : "+614123123121" },
{ "destination" : "+614123123120" }
]
}
To generate a POST request including parameters, the ‘members’ field (above) will need to contain the parameters you want in the content:
| FIELD | DESCRIPTION | TYPE | SUB TYPE | REQUIRED |
|---|---|---|---|---|
| destination | The mobile number to send the content to | string | yes | |
| param1 | Substitution parameter to include within the content | string | no | |
| param2 | Substitution parameter to include within the content | string | no | |
| param3 | Substitution parameter to include within the content | string | no | |
| param4 | Substitution parameter to include within the content | string | no | |
| param5 | Substitution parameter to include within the content | string | no | |
| param6 | Substitution parameter to include within the content | string | no |
For demonstrative purposes only:
{
"name" : "List Name",
"members" : [
{ "destination" : "+614123123123", "param1" : "Bob" },
{ "destination" : "+614123123122", "param1" : "Sarah" },
{ "destination" : "+614123123121", "param1" : "Tyler" },
{ "destination" : "+614123123120", "param1" : "Paul" }
]
}
To Delete a List
Submit a HTTP DELETE request using the following form to delete a list:
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/lists/{list_id}
On success:
HTTP/1.1 204 List Deleted
To Delete Multiple Lists
Submit a HTTP POST request using the following form to delete a list:
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/delete_multiple_lists
Use the following attribute in the request body:
| FIELD | DESCRIPTION | TYPE | SUB TYPE | REQUIRED |
|---|---|---|---|---|
| list_ids | List of IDs to be deleted | array | integer | Yes |
For demonstrative purposes only, an example of a request body:
{
"list_ids" : [
1234, 3456, 5678
]
}
On success, the following response is returned:
HTTP/1.1 200
{"list_ids":[1234, 3456, 5678],"message":"Deleted list ids"}
NOTE: if not all lists can be deleted, the request is still considered successful, and the response will only include the deleted list IDs.
GET all Lists
Submit a HTTP GET request using the following form to get all lists associated to a campaign application.
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/lists
On success:
HTTP/1.1 200 OK
[
{
"created":"2019-10-04T10:12:19.011Z",
"id":123456,
"name":"string",
"members":[
{
"destination":"+123456789",
"param1":"string",
"param2":"string",
"param3":"string",
"param4":"string",
"param5":"string",
"param6":"string"
},
{
"destination":"+123456789",
"param1":"string",
"param2":"string",
"param3":"string",
"param4":"string",
"param5":"string",
"param6":"string"
}
]
}
]
Error Codes
The following errors can occur:
| Code | Description |
|---|---|
| 401 - Unauthorised | Incorrect username and/or password |
| 403 - Forbidden | Not allowed access to the application, or, not allowed access to campaign manager |
| 404 - Not Found | URL is wrong or List has already been deleted |
| 422 - Unprocessable Entity | Validation errors within the data |
| 4xx - | Something else is wrong with the request |
| 5xx - | Something is wrong with the service |
Sample error:
{
"code" : 401,
"message" : "unauthenticated for invalid credentials"
}
To generate your own client libs, click here.
API Reports
This page describes the resources that make up the Campaign Manager REST API v1 for dealing with campaign report it is intended for developers who want to integrate a data source directly into the Campaign Manager application.
The Mobile Gateway REST API provides access to resources (data entities) via URI paths. To use this API, your application will make an HTTP request and parse the response. The response format is JSON.
Authentication
HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.
Your Campaign Manager API credentials are the same as used to login. Navigate to the Campaign Manager application under ‘Send Messages’, and view the ‘API Info’ tab to obtain your API details.
If you don’t have these details, please contact optussd@modicagroup.com .
Base URI
All API access is over HTTPS, and accessed from
https://api.sms.optus.com.au/campaign_manager/v1/application_name/{campaign_id}/report
Versions
The Campaign Manager API version is currently v1.
GET a report summary
Submit a HTTP GET request using the following form to get a report associated to a campaign message.
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/{campaign_id}/report
On success:
HTTP/1.1 200 OK
[
{
"list_name":"string",
"message_id":123456789,
"mobile":"+64123456",
"sent_date":"2019-02-19 15:48:01.894677",
"status":"received",
"status_date":"2019-02-19 15:48:03.498389",
"timezone":"Pacific/Auckland"
},
{
"list_name":"string",
"message_id":123456789,
"mobile":"+6412345678",
"sent_date":"2019-02-19 15:48:01.744065",
"status":"failed",
"status_date":"2019-02-19 15:48:03.192748",
"timezone":"Pacific/Auckland"
}
]
Error Codes
The following errors can occur:
| Code | Description |
|---|---|
| 401 - Unauthorised | Incorrect username and/or password |
| 403 - Forbidden | Not allowed access to the application, or, not allowed access to campaign manager |
| 404 - Not Found | URL is wrong |
| 422 - Unprocessable Entity | Validation errors within the data |
| 4xx - | Something else is wrong with the request |
| 5xx - | Something is wrong with the service |
Sample error:
{
"code" : 401,
"message" : "unauthenticated for invalid credentials"
}
To generate your own client libs, click here .
API Templates
This page describes the resources that make up the Campaign Manager REST API v1 for dealing with templates it is intended for developers who want to integrate a data source directly into the Campaign Manager application.
The Mobile Gateway REST API provides access to resources (data entities) via URI paths. To use this API, your application will make an HTTP request and parse the response. The response format is JSON.
Authentication
HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.
Your Campaign Manager API credentials are the same as used to login. Navigate to the Campaign Manager application under ‘Send Messages’, and view the ‘API Info’ tab to obtain your API details.
If you don’t have these details, please contact optussd@modicagroup.com.
Base URI
All API access is over HTTPS, and accessed from
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/templates
Versions
The Campaign Manager API version is currently v1.
GET all Templates
Submit a HTTP GET request using the following form to get all templates associated to a campaign application.
https://api.sms.optus.com.au/rest/campaign_manager/v1/application_name/templates
On success:
HTTP/1.1 200 OK
[
{
"id":123,
"name":"template_name"
}
]
Error Codes
The following errors can occur:
| Code | Description |
|---|---|
| 401 - Unauthorised | Incorrect username and/or password |
| 403 - Forbidden | Not allowed access to the application, or, not allowed access to campaign manager |
| 404 - Not Found | URL is wrong |
| 422 - Unprocessable Entity | Validation errors within the data |
| 4xx - | Something else is wrong with the request |
| 5xx - | Something is wrong with the service |
Sample error:
{
"code" : 401,
"message" : "unauthenticated for invalid credentials"
}
To generate your own client libs, click here .
