Text messages

Use this endpoint to obtain details on Mautic’s Text Messages, or SMSs.

Text message properties

Use these properties when creating a Text Message in a POST request. These properties are also returned when listing or getting Text Messages.

Name	Type	Description
`id`	int	ID of the SMS
`name`	string	Title of the SMS
`message`	string	Message of the SMS
`isPublished`	boolean	Published state
`publishUp`	datetime/null	Date/time when the SMS gets published
`publishDown`	datetime/null	Date/time the SMS gets unpublished
`dateAdded`	`datetime`	Date/time SMS got created
`createdBy`	int	ID of the User that created the SMS
`createdByUser`	string	Name of the User that created the SMS
`dateModified`	datetime/null	Date/time SMS got last modified
`modifiedBy`	int	ID of the User that last modified the SMS
`modifiedByUser`	string	Name of the User that last modified the SMS
`language`	string	Language locale of the SMS
`sentCount`	int	How many times the SMS got sent

Using Mautic’s API Library

You can interact with this API through the Mautic API Library as follows, or use the various http endpoints as described in this document.

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://example.com";
$api      = new MauticApi();
$smsApi   = $api->newApi("smses", $auth, $apiUrl);

Get text message

<?php

//...
$sms = $smsApi->get($id);

Get an individual SMS by ID.

HTTP Request

GET /smses/ID

Response

Expected Response Code: 200

{
    "sms":{
        "isPublished":true,
        "dateAdded":"2016-09-14T12:14:45+00:00",
        "createdBy":1,
        "createdByUser":"Wu Popovski",
        "dateModified":null,
        "modifiedBy":null,
        "modifiedByUser":null,
        "id":1,
        "name":"Message A",
        "message":"Hello",
        "language":"en",
        "category":null,
        "publishUp":null,
        "publishDown":null,
        "sentCount":0
    }
}

List text messages

<?php
// ...

$smses = $smsApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP Request

GET /smses

Query Parameters

Name	Description
`search`	String or search command to filter entities by.
`start`	Starting row for the entities returned. Defaults to 0.
`limit`	Limit number of entities to return. Defaults to the system configuration for pagination, which defaults to 30.
`orderBy`	Column to sort by. Can use any column listed in the response.
`orderByDir`	Sort direction: `asc` or `desc`.
`publishedOnly`	Only return currently published entities.
`minimal`	Return only array of entities without additional lists in it.

Response

Expected Response Code: 200

{
    "total":1,
    "smses":[
        {
            "isPublished":true,
            "dateAdded":"2016-09-14T12:14:45+00:00",
            "createdBy":1,
            "createdByUser":"Kevin Bulgarelli",
            "dateModified":null,
            "modifiedBy":null,
            "modifiedByUser":null,
            "id":1,
            "name":"Message A",
            "message":"Hello",
            "language":"en",
            "category":null,
            "publishUp":null,
            "publishDown":null,
            "sentCount":0
        }
    ]
}

Properties

See the “Text message properties” on top of this document.

Create text message

<?php

$data = array(
    'name'        => 'Text message A',
    'message' => 'This is my first sms created via API.',
    'isPublished' => 1
);

$sms = $smsApi->create($data);

Create a new SMS.

HTTP Request

POST /smses/new

POST Parameters

See the “Text message properties” on top of this document.

Response

Expected Response Code: 201

Properties

See the “Text message properties” on top of this document.

Edit text message

<?php

$id   = 1;
$data = array(
    'name'        => 'New sms name',
    'isPublished' => 0
);

// Create new a SMS of ID 1 is not found?
$createIfNotFound = true;

$sms = $smsApi->edit($id, $data, $createIfNotFound);

Edit a new SMS. Note that this supports PUT or PATCH depending on the desired behavior.

PUT creates an SMS if the given ID doesn’t exist and clears all the SMS information, adds the information from the request. PATCH fails if the SMS with the given ID doesn’t exist and updates the SMS field values with the values from the request.

HTTP Request

To edit an SMS and return a 404 if the SMS isn’t found:

PATCH /smses/ID/edit

To edit an SMS and create a new one if the SMS isn’t found:

PUT /smses/ID/edit

PUT/PATCH Parameters

Name	Type	Description
`id`	int	ID of the SMS
`name`	string	Title of the SMS
`message`	string	Message of the SMS
`isPublished`	boolean	Published state
`publishUp`	datetime/null	Date/time when the SMS should gets published
`publishDown`	datetime/null	Date/time the SMS should gets unpublished
`language`	string	Language locale of the SMS

Response

If PUT, the expected response code is 200 if the SMS got edited or 201 if created.

If PATCH, the expected response code is 200.

Properties

See the “Text message properties” on top of this document.

Delete text message

<?php

$sms = $smsApi->delete($id);

Delete an SMS.

HTTP Request

DELETE /smses/ID/delete

Response

Expected Response Code: 200

Properties

See the “Text message properties” on top of this document.

Send SMS to contact

<?php

$sms = $smsApi->sendToContact($smsId, $contactId);

Send a predefined SMS to existing Contact.

HTTP Request

GET /smses/ID/contact/CONTACT_ID/send

Response

Expected Response Code: 200

Properties

{
    "success": 1,
    "status": "Delivered"
}