Send an MMS with Cellcast RESTful API

With our MMS messaging API you can:

  1. Send MMS messages.
  2. Receive real time delivery reports (DLR) for all messages sent.
  3. Receive replies and inbound MMS messages.

MMS stands for Multimedia Messaging Service. Multimedia Messaging Service is an extension of the core SMS protocol, and it was developed to enable the transmission of multimedia content via text message.

MMS messages cost a bit more than SMS messages because it involves the transmission of more data.

In case you're wondering, "Why pay more for MMS?", the answer is pretty easy: MMS campaigns have a 20% higher opt-in rate than SMS campaigns, and MMS messages are 8x more likely to be shared on social media. Pics and gifs are simply much more engaging than plain old text, and that’s why it's worth paying more for MMS.

MMS creates a richer mobile experience for your customers or subscribers. A picture is worth a thousand words.


Our simple REST API allows you to get up and running in minutes, just follow the helpful Quick Start guide. For advanced users, dig deeper into our technology and check our reference guides for more detailed functions and calls. We have a wide range of calls to mirror useful functionality on the site at both user and reseller level. We also offer code samples in order to make your experience using the API suite as clean as possible.

So let's now look at how to use and get the best out of the REST API.



Security

To ensure security & privacy the API only works over HTTPS protocol for all requests. Also, for your own security, If you have a website with a form which sends MMS be sure to send the request from your server and not directly from the browser otherwise you will be giving away your API secret and opening the floodgates to unwanted charges.


Authentication

All API requests require your API credentials, We will provide you APPKEY. For Security API credentials must be passed as HTTP Basic Authentication headers not as CGI parameters.


Throttling

To provide the best service to all our customers we limit the number of API calls.If you exceed this limit we will return two indicators which you can use in your code to detect that you have been throttled. The first is the HTTP status code 429 "Too Many Requests", the second is the error code "OVER_LIMIT" in the error block of the response body.


Pagination

Some responses are too large to be returned in one go so we paginate. To identify which calls use pagination look for the "page" parameters in the parameter descriptions for each API call. These calls include a "page" block in the response with two values, "count" and "number". Count tells you how many pages are available and number indicates the page number you are on. The page parameter is used to request a certain page, it defaults to 1. The max parameter is used to limit the number of results returned per page, the default is 25.


Error Reporting

Always check if your API call was successful or resulted in error. You may check the following

  1. 200 OK response header. It will be 4xx if an error occurred.
  2. error->code structure should equal to 'SUCCESS'Note that some API functions can return custom errors of their own (listed in appropriate document sections). Check the error->description for details, e.g. which field caused an error or which resource you don’t have access to.

We can't wait to see what you build!

send-mms

Base URL:

https://cellcast.com.au/api/v3/send-mms
Method: POST (Form data)

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY. Which is linked to your cellcast account
Content-Type multipart/form-data

MMS Data Parameters

Name Example Description
subject MMS subject goes here string - Required field
mms_text MMS text goes here string - Required field
mms_file MMS Image file goes here Only PNG, GIF and JPEG are allowed and Max Image size 300KB.
- Please upload size 300x450px
- Required field
numbers ["+61400000000"] JSON encoded Array - Required field
For multiple MMS send: ["+61400000000","+61400000001"]
You can pass 10000 numbers to send an MMS in one API call
- Required field

Success Responses

Code Status Description
200 SUCCESS "campaign_id" for get reports of campaign.
You will get MMS scheduled count and credit deduction count.

Success Responses looks like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Your MMS campaign is successfully scheduled.",
    "data": {
        "campaign_id": "16",
        "total_numbers": 2,
        "success_number": "2",
        "unsubscribed_number": 0,
        "credits_used": "2"
    }
}

campaign_id usage:

On each send-mms API call, a campaign will be generated in the system and return response with "campaign_id". So in the future, you can fetch all details of the campaign - pass campaign_id to gain campaign details.

"campaign_id" is the main ID for retrieving your entire campaign details. Using Campaign id, you can get the following details:

- MMS total sent count and undeliverable count
- MMS optout numbers list
- MMS Responses
- MMS full report


Error Responses

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided APPKEY
AUTH_FAILED 401 - APPKEY you have provided is invalid
- You are not a registered user
FIELD_EMPTY 400 Required field is empty
RECIPIENTS_ERROR 400 No valid recipients left after validation or recipient in unsubscribed list.
FIELD_INVALID 400 -You can pass 10000 numbers to send an MMS in one API call
- You do not have enough credit to send MMS.
- You can pass text up to 1000 characters to send an MMS.
- You can pass the subject up to 40 characters to send an MMS.
- Choose image file to upload.
- Upload valid image. Only PNG, GIF and JPEG are allowed.
- Image size exceeds 380KB
- Problem in uploading image files.
BAD_REQUEST 400 Please provide proper data

Error Responses looks like:

{
    "meta": {
        "code": 400,
        "status": "FIELD_INVALID"
    },
    "msg": "You can pass text up to 1000 characters to send an MMS.",
    "data": []
}

PHP Code Example

You can call following function to send MMS.

function sendMms($form_data) {
    try {
        $url = 'https://cellcast.com.au/api/v3/send-mms'; //API URL
        $headers = array(
            'APPKEY: <<APPKEY>>',
            'Accept: application/json',
            "cache-control: no-cache",
            'Content-Type: multipart/form-data',
        );

        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $form_data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully send mms", "result" => json_decode($result)));
    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}
                                

Call Function

//Call function to send MMS and pass form submitted data
sendMms($form_data);
                                

get-status

Base URL:

https://cellcast.com.au/api/v3/get-status?campaignID=<<campaignID>>
Method: GET

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY. Which is linked to your cellcast account
Content-Type application/json

API Parameters

Name Example Description
campaignID Campaign id which is return by "send-mms" API campaign id - Required field

Success Responses

Code Status Description
200 SUCCESS Total sent <<number of delivered count>>

Success Responses looks like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Total sent 1",
    "data": {
        "campaignID": "4",
        "recipientCount": "1",
        "sent": "1",
        "undeliverable": "0"
    }
}

Error Responses

Status Code Description
FIELD_INVALID 400 Invalid Campaign ID
NOT_EXISTS 400 The campaign has not been founded

Error Responses looks like:

{
    "meta": {
        "code": 400,
        "status": "FIELD_INVALID"
    },
    "msg": "Invalid Campaign ID",
    "data": []
}

PHP Code Example

You can call following function to get MMS status.

function getMmsStatus($campaign_id) {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-status?campaignID=' . $campaign_id; //API URL
        $headers = array(
            'APPKEY: <<APPKEY>>',
            'Accept: application/json',
            'Content-Type: application/json',
        );

        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 4);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully received", "result" => json_decode($result)));

    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}
                                

Call Function

//Call function to get mms status function
$response_status = getMmsStatus(<<campaignID>>);
                                

get-responses

Base URL:

https://cellcast.com.au/api/v3/get-responses?campaignID=<<campaignID>>&page=<<page_number>>
Method: GET

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY. Which is linked to your cellcast account
Content-Type application/json

API Parameters

Name Example Description
campaignID Campaign id which is return by "send-mms" API campaign id - Required field
page Page number Pass page number.Default value is 1

Success Responses

Code Status Description
200 SUCCESS You have <<Total Responses>> response(s)

Success Responses looks like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "You have 1 response(s)",
    "data": {
        "campaignID": "2",
        "page": {
            "count": 1,
            "number": 1
        },
        "total": "1",
        "responses": [
            {
                "number": "+614NNNNNNNN",
                "response": "Hi response",
                "received_at": "17 Dec, 18 06:18:14 AM"
            }
        ]
    }
}

Error Responses

Status Code Description
FIELD_INVALID 400 - Invalid Campaign ID or Page parameter
- Invalid Campaign ID
AUTH_FAILED 400 You are not a registered user
AUTH_FAILED 400 You are not a registered user
NOT_FOUND 400 No Response are available!
NOT_EXISTS 400 The campaign has not been founded

Error Responses looks like:

{
    "meta": {
        "code": 400,
        "status": "NOT_EXISTS"
    },
    "msg": "The campaign has not been founded",
    "data": {
        "campaignID": "9",
        "page": {
            "count": "0",
            "number": 0
        },
        "total": 0,
        "responses": ""
    }
}

PHP Code Example

You can call following function to get MMS responses.

function getMmsResponses($campaign_id,$page = 1) {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-responses?campaignID=' . $campaign_id. '&page=' .$page; //API URL
        $headers = array(
            'APPKEY: <<APPKEY>>',
            'Accept: application/json',
            'Content-Type: application/json',
        );

        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 4);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully received", "result" => json_decode($result)));

    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}
                                

Call Function

//Call function to get mms status function
$response_status = getMmsResponses(<<campaignID>>,<<page_number>>);
                                

get-optout

Base URL:

https://cellcast.com.au/api/v3/get-optout?campaignID=<<campaignID>>
Method: GET

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY. Which is linked to your cellcast account
Content-Type application/json

MMS Data Parameters

Name Example Description
campaignID Campaign id which is return by "send-mms" API campaign id - Required field

Success Responses

Code Status Description
200 SUCCESS You have <<Total optout>> optout(s)

Success Responses looks like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "You have 2 optout(s)",
    "data": {
        "campaignID": "4",
        "total": 2,
        "optouts": [
            {
                "number": "+614NNNNNNNN",
                "received_at": "25 Dec, 18 12:00:00 AM"
            },
            {
                "number": "+614NNNNNNNN",
                "received_at": "25 Dec, 18 12:00:00 AM"
            }
        ]
    }
}

Error Responses

Status Code Description
FIELD_INVALID 400 Invalid Campaign ID
NOT_FOUND 400 No optout are available!

Error Responses looks like:

{
    "meta": {
        "code": 400,
        "status": "FIELD_INVALID"
    },
    "msg": "Invalid Campaign ID",
    "data": []
}

PHP Code Example

You can call following function to get MMS Optout.

function getMmsOptout($campaign_id) {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-optout?campaignID=' . $campaign_id; //API URL
        $headers = array(
            'APPKEY: <<APPKEY>>',
            'Accept: application/json',
            'Content-Type: application/json',
        );

        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 4);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully received", "result" => json_decode($result)));

    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}

Call Function

//Call function to MMS optout count
$list_optout = getMmsOptout($campaign_id);
                                

Global Opt Out

The Global Opt-Out (GOO) is an account wide function that allows for automated SPAM compliance with a minimum of hassle on your side.

All recipients who reply with the word 'STOP'(In any case) to any of your messages will be automatically added to the GOO. All outbound messages are checked against the GOO and messages sent to any numbers on this list will be prevented from delivering.

We have provided the option in the Client API Settings page to disable the GOO functionality. Default option is ON for all user.

get-report

Base URL:

https://cellcast.com.au/api/v3/get-report?campaignID=<<campaignID>>
Method: GET

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY. Which is linked to your cellcast account
Content-Type application/json

MMS Data Parameters

Name Example Description
campaignID Campaign id which is return by "send-mms" API campaign id - Required field

Success Responses

Code Status Description
200 SUCCESS Campaign Details

Success Responses looks like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Campaign Details",
    "data": {
        "campaignID": "4",
        "recipientCount": "1",
        "sent": "1",
        "undeliverable": "0",
        "responses": "21",
        "unsubscribed": "2"
    }
}

Error Responses

Status Code Description
FIELD_INVALID 400 Invalid Campaign ID
NOT_EXISTS 400 The campaign has not been founded

Error Responses looks like:

{
    "0": {
        "campaignID": "16",
        "recipientCount": 0,
        "sent": 0,
        "undeliverable": 0,
        "responses": 0,
        "unsubscribed": 0
    },
    "meta": {
        "code": 400,
        "status": "NOT_EXISTS"
    },
    "msg": "The campaign has not been founded"
}

PHP Code Example

You can call following function to get MMS Report.

function getMmsReport($campaign_id) {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-report?campaignID=' . $campaign_id; //API URL
        $headers = array(
            'APPKEY: <<APPKEY>>',
            'Accept: application/json',
            'Content-Type: application/json',
        );

        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 4);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully received", "result" => json_decode($result)));

    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}

Call Function

//Call function to get MMS Report
$report_details = getMmsReport($campaign_id);
                                

MMS character count

What is the structure of an MMS?

  • Subject Line: 40 characters max
  • Creative: Image, gif
  • Message Copy: 1000 characters max

When sending text and pictures in the same message, a message can contain up to 1 image and 1000 characters.

You can send the maximum subject length of 40 characters.

Please note, some special characters(Unicode charset) count for more than 1 character in a text message, which can affect character count (and therefore, size) in messages


What characters are part of the Unicode charset?

The Unicode character list contains symbols from the Cyrillic, Chinese, Arabic, Korean and Hangul alphabets. It also contains several special symbols (such as emoticons, emoji and kanji).

Unicode character list: here


GSM Charset: The GSM 03.38 charset is the standard character set for text messaging on GSM-based cell phones. All GSM handsets and network elements support the GSM 7-bit alphabet. The basic GSM charset contains the letters A to Z (uppercase and lowercase), numbers, special symbols and several symbols from the Greek alphabet.

@	Δ	SP	0	¡	P	¿	p
£	_	!	1	A	Q	a	q
$	Φ	"	2	B	R	b	r
¥	Γ	#	3	C	S	c	s
è	Λ	¤	4	D	T	d	t
é	Ω	%	5	E	U	e	u
ù	Π	&	6	F	V	f	v
ì	Ψ	'	7	G	W	g	w
ò	Σ	(	8	H	X	h	x
Ç	Θ	)	9	I	Y	i	y
LF	Ξ	*	:	J	Z	j	z
Ø	ESC	+	;	K	Ä	k	ä
ø	Æ	,	<	L	Ö	l	ö

Escape Characters: Some characters in the GSM 03.38 extension table can only be used at the cost of two characters. The GSM charset uses 7-bit alphabet encoding, but the escape characters require 14 bits to encode, thus taking up two characters. These symbols are:  |, ^, {, }, €, [, ~, ] and \.

Unicode Symbols: Unicode is a standard for encoding, handling and representing the text expressed in many of the world’s writing systems. The latest list of Unicode symbols contains over 120,000 characters from multiple symbol sets and 129 historic and modern scripts.

Unicode Encoding: Compared to the GSM charset, Unicode encoding supports a huge range of languages and symbols. However, if your text message contains a symbol that isn’t in the 7-bit alphabet, UCS-2 encoding must be used. This type of encoding takes up a lot of space, thus reducing the number of characters allowed in a message to 70.

MMS Image requirements

Supported media types for MMS

MMS on Cellcast offers full support for common image file types: png, jpeg, and gif.

For sending MMS messages, please review Cellcast's Accepted Content Types for Media for fully supported media file support.

Total message size must be under 350kb. An API request with media and Content larger than 350kb will fail with an error.


The following types of content are fully supported by Cellcast for Media. This content will be formatted for delivery on destination devices.

  1. image/jpeg
  2. image/gif
  3. image/png

Mobile format

Australian Mobile format

You can send an MMS to any Australian Mobile number.

Allocation for numbers in the range 04xy z00 000 – 04xy z99 999


Valid Mobile Numbers format:

  1. +614NNNNNNNN
  2. 04NNNNNNNN

Help

Contact us

Email: info@cellcast.com.au
Melbourne Head Office:
40 Porter St, Prahran, VIC 3181, Australia
Australia & NZ: +61 (03) 8560 7025


Get in touch, send us a message to arrange a coffee catch-up