Private Messages API

The Private Messages API provides endpoints for managing private messages between users in Joomla.

Base URL

/api/index.php/v1/messages

Endpoints Overview

Method	Endpoint	Description
GET	/messages	Retrieve all messages
GET	/messages/{id}	Retrieve specific message
POST	/messages	Send new message
PATCH	/messages/{id}	Update message
DELETE	/messages/{id}	Delete message

Retrieve all messages

GET /api/index.php/v1/messages

Response

{
    "data": [
        {
            "type": "messages",
            "id": "1",
            "attributes": {
                "user_id_from": 42,
                "user_id_to": 43,
                "subject": "Welcome to the team",
                "message": "Hello and welcome!",
                "state": 0,
                "date_time": "2024-01-15 10:30:00",
                "priority": 0,
                "folder_id": 0
            }
        }
    ]
}

Retrieve specific message

GET /api/index.php/v1/messages/{id}

Parameters

Parameter	Type	Description
id	integer	Message ID

Example

curl -X GET "https://yoursite.com/api/index.php/v1/messages/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Send message

POST /api/index.php/v1/messages

Request Body

{
    "user_id_to": 43,
    "subject": "Message subject",
    "message": "This is the content of the private message."
}

Required fields

Field	Type	Description
user_id_to	int	Recipient user ID
subject	string	Subject
message	string	Message content

Optional fields

Field	Type	Default	Description
priority	int	0	Priority (0=normal, 1=high)

Example

curl -X POST "https://yoursite.com/api/index.php/v1/messages" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id_to": 43,
    "subject": "Important update",
    "message": "A new version is available."
  }'

Update message

PATCH /api/index.php/v1/messages/{id}

Request Body

{
    "state": 1
}

Example: Mark as read

curl -X PATCH "https://yoursite.com/api/index.php/v1/messages/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state": 1
  }'

Delete message

DELETE /api/index.php/v1/messages/{id}

Example

curl -X DELETE "https://yoursite.com/api/index.php/v1/messages/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Note

Deleted messages cannot be recovered.

Message States

Value	Status
0	Unread
1	Read

Message Priorities

Value	Priority
0	Normal
1	High

Folder IDs

Value	Folder
0	Inbox
1	Sent
2	Trash

Filtering

By status (read/unread)

GET /api/index.php/v1/messages?filter[state]=0

By sender

GET /api/index.php/v1/messages?filter[user_id_from]=42

By folder

GET /api/index.php/v1/messages?filter[folder_id]=0

Count unread messages

To get the number of unread messages:

curl -X GET "https://yoursite.com/api/index.php/v1/messages?filter[state]=0" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Count the number of items in the response.

Example: Bulk send messages

#!/bin/bash
# Send message to multiple users

users=(43 44 45 46)
subject="Newsletter"
message="Check out our latest updates!"

for user_id in "${users[@]}"; do
    curl -X POST "https://yoursite.com/api/index.php/v1/messages" \
      -H "X-Joomla-Token: YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{
        \"user_id_to\": $user_id,
        \"subject\": \"$subject\",
        \"message\": \"$message\"
      }"
done

Limitations

• Messages are only available for backend (administrator) users
• The API token must be from a user with access to the Messages component
• Messages are not automatically sent via email (this is a Joomla configuration)

info

Private Messages in Joomla are intended for communication between administrators. For frontend user messaging, you need a separate extension.