Pending messages

Notifications flow

To consume new (unread) messages from your integration, use /messages notifications to identify sales with new messages. Then perform a GET request on each pack to retrieve the message details.

Messages pending reading

This resource allows you to retrieve all pending (unread) messages in Mercado Libre for existing orders. You can filter by specific orders and define the user role (buyer or seller). This endpoint is recommended for redundancy validation to ensure no messages were lost during notification processing.

Remember that when you call /messages/packs/{pack_id}/sellers/{seller_id} the messages will be automatically marked as read. To prevent this, add the mark_as_read=false parameter to your query: /messages/packs/{pack_id}/sellers/{seller_id}?mark_as_read=false.

Parameters

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/unread

Response:

{
    "results": [
        {
            "resource": "/packs/123123123",
            "count": 1
        },
        {
            "resource": "/packs/1231234123",
            "count": 1
        }
    ],
    "userId": 29293123
}

Response fields

Use modes

If you want to get all the orders with messages pending reading as seller, you will need to make this request:

curl --location 'https://api.mercadolibre.com/marketplace/messages/unread?role=$ROLE&tag=post_sale&user_id=$USER_ID' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

The possible values for role are buyer or seller.

Response:

{
    "results": [
        {
            "resource": "/packs/12312312",
            "count": 1
        }
    ],
    "userId": 123123
}

If there are no messages pending reading for the user's orders, or if the specified orders do not belong to the user, the response will be:

{
    "userId": 1234512314,
    "results": []
}

Mark messages as read

Use this endpoint to retrieve messages from a specific pack and automatically mark them as read. The response includes conversation status, paging information, and full message details including attachments.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$SELLER_ID?limit=$LIMIT&offset=$OFFSET&tag=post_sale

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?limit=2&offset=1&tag=post_sale

To retrieve messages without marking them as read:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?limit=2&offset=1&tag=post_sale&mark_as_read=false

Response:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 31
    },
    "conversation_status": {
        "path": "/packs/2000000089077943/seller/415458330",
        "status": "active",
        "substatus": null,
        "status_date": "2019-04-08T16:36:30.000Z",
        "status_update_allowed": false,
        "claim_id": null,
        "shipping_id": null
    },
    "messages": [
        {
            "id": "2c92808469fea23a0169febf14580001",
            "site_id": "MLM",
            "client_id": 123,
            "from": {
                "user_id": "415458330",
                "email": "test_user_83388960@testuser.com",
                "name": "Juan Pablo Robledo"
            },
            "status": "IN_MODERATION",
            "text": "Test message ToUserId",
            "message_date": {
                "received": "2019-04-08T20:58:49.000Z",
                "available": null,
                "notified": null,
                "created": "2019-04-08T20:58:49.000Z",
                "read": "2019-04-08T20:58:52.000Z"
            },
            "message_moderation": {
                "status": "NON_MODERATED",
                "reason": "none",
                "by": "none",
                "moderation_date": null
            },
            "message_attachments": [
                {
                    "filename": "415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf",
                    "original_filename": "Ayuda-Memoria-Arduino-ELINSI.pdf",
                    "type": "application/octet-stream",
                    "size": 225677,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-08T20:58:49.000Z"
                }
            ],
            "message_resources": [
                {
                    "id": "2000000089077943",
                    "name": "packs"
                },
                {
                    "id": "415458330",
                    "name": "seller"
                }
            ]
        }
    ]
}

Response fields

Errors

Next: Blocked messages.