Post-sale messages

Important:
Starting July 30, 2021, we will remove the name and email fields from the Messaging resource.

The messaging API resource will enable you to get messages from a specific order, create new messages in the system, and send or receive attachments.

Contents

→Parameters
→Get messages by pack
→Get messages by ID
→Create messages for a buyer
→Save message and attach file
→Get attachment
→Errors
   

Parameters

from: message sender.
user_id: user id who sent message.
to: message recipient.
user_id: user id who received message.
text: message text.
attachments: attached files.
site_id: Mercado Libre México, Brazil, Colombia, Chile (MLM, MLB, MCO, MLC) site.


Get messages by pack 

To get the messages of a particular pack you must make a request associating the pack_id and the user_id, corresponding to the seller of the package, with the resource /marketplace/messages. Remember messages moderated by the counterpart will not be visible and the messages themselves will be visible.

Request:

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

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/messages/packs/2315686468?limit=2&offset=1

Response:

{
  "paging": {
    "limit": 1,
    "offset": 0,
    "total": 1
  },
  "conversation_status": {
    "claim_ids": null,
    "shipping_id": null,
    "status": "active",
    "status_date": "2020-02-26T17:37:42Z",
    "status_update_allowed": false,
    "substatus": null
  },
  "messages": [{
    "id": "2d45a5ad186041659e9a608f0c109dff",
    "site_id": "MLM",
    "client_id": 1344270061107690,
    "from": {
      "user_id": 523132944,
      "name": "TESTNICOCBT TESTNICOCBT"
    },
    "to": {
      "user_id": 441782523,
      "name": "Test Test"
    },
    "status": "available",
    "subject": null,
    "text": "This a message to buyer",
    "message_date": {
      "received": "2020-03-13T15:14:10Z",
      "available": "2020-03-13T15:14:10Z",
      "notified": null,
      "created": "2020-03-13T15:14:10Z",
      "read": null
    },
    "message_moderation": {
      "status": "clean",
      "reason": null,
      "source": "online",
      "moderation_date": "2020-03-13T15:14:10Z"
    },
    "message_attachments": [{
        "filename": "471826944_ba20cdf4-26b4-4c21-a689-5eabe271ddb3.png",
        "original_filename": "FileName.png",
        "type": "image/png",
        "size": 536766,
        "potential_security_threat": false,
        "creation_date": "2020-03-13T15:14:10Z"
      },
      {
        "filename": "523130418_10f6b123-5ec2-44dc-b611-e347098331a2.png",
        "original_filename": "FileName.png",
        "type": "image/png",
        "size": 536766,
        "potential_security_threat": false,
        "creation_date": "2020-03-13T15:14:10Z"
      }
    ],
    "message_resources": [{
        "id": "2315686468",
        "name": "packs"
      },
      {
        "id": "523132944",
        "name": "sellers"
      }
    ],
    "conversation_first_message": false,
    "text_translated": "Este es un mensaje para el comprador"
  }]
}
Note:
Remember that the time zone for these dates is UTC.

Get message by ID

To know the messages associated with a pack, you must make a query to the resource /marketplace/messages.

Note:
From November 7, 2021 we will return only the updated response, without the need to include the header ''New-Format = true''.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/messages/$MESSAGE_ID
{
    "paging": null,
    "conversation_status": null,
    "messages": [
        {
            "id": "testmessage1123456",
            "site_id": "MLM",
            "client_id": 818828848883,
            "from": {
                "user_id": "1234567",
                "name": ""
            },
            "to": {
                "user_id": "7654321",
                "name": ""
            },
            "status": "available",
            "subject": null,
            "text": "",
            "message_date": {
                "received": "2021-09-26T04:48:25Z",
                "available": "2021-09-26T04:48:25Z",
                "notified": "2021-09-26T04:48:25.000Z",
                "created": "2021-09-26T04:48:25Z",
                "read": null
            },
            "message_moderation": {
                "status": "clean",
                "reason": null,
                "source": "online",
                "moderation_date": "2021-09-26T04:48:25Z"
            },
            "message_attachments": null,
            "message_resources": [
                {
                    "id": "2000002725708674",
                    "name": "packs"
                },
                {
                    "id": "534272725",
                    "name": "sellers"
                }
            ],
            "conversation_first_message": false,
            "text_translated": "Este es un mensaje de prueba"
        }
    ]
}

Save message and attach file

To attach a file in the message, you need to save it first. Then, when the attachment is sent, the file id is returned as response.
Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/messages/attachments
Notes:
- The POST needs to be made form.data with key: value > file = reference to file (that is, the file itself).
- The file needs to have a maximum 25 MB size.
- You can exchange pictures, instruction manuals, invoices, and any other attachments of up to 25 MB in JPG, PNG, PDF and TXT format.
- The allowed Mime Types of files are:
text/plain
image/png
image/jpeg
image/heif
image/heic
application/pdf
application/msword
application/vnd.ms-excel
text/xml,application/xml
application/octet-stream
If you want to upload any that are not listed, the API will return an HTTP Status Code 400.

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST \ 'https://api.mercadolibre.com/marketplace/messages/attachments' \
  -H 'content-type: multipart/form-data;' \
  -F 'file=@/home/user/.../Adjunto.jpg'

In this case, the server will respond with a JSON containing file id in case of a successful request.

Note:
The response obtained should be attached to the intended message.

Response:

{
  "id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}

 

Create messages for a buyer

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/messages/packs/$ORDER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST http://api.mercadolibre.com/marketplace/messages/packs/2315686468 \
  -H 'content-type: application/json' \
  -d '{
    "text": "More test message",
    "text_translated": "",
    "attachments": [
        "471826944_ba20cdf4-26b4-4c21-a689-5eabe271ddb3.png",
        "523130418_10f6b123-5ec2-44dc-b611-e347098331a2.png"
    ]
}
Notes:
- The attachments attribute is obtained from the attachment POST response. Learn more how upload and save attachment.
- If you don't need to attach a file, you can remove the "attachments" section in the JSON.
- If you want to create a message with the buyer language, use the “text_translated” field.
- If you need to insert a link that can be clicked, you can do so using the href function. For example: "<a href="your_url"> Your tracking link </a>".

Get attachment

To get an attached message, you need to make a GET.
Request:

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

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png

Response:
If the request is successful, the call will return the requested file. In case the file cannot be accessed, the server response will be the following:

{
    "message": "File can not be accessed, try it later",
    "error": null,
    "status": 500,
    "cause": []
}

In case the access token is not sent, the message will be:

{
    "message": "Access token is required",
    "error": "bad_request",
    "status": 400,
    "cause": []
}


Possible errors

Errors to get message by ID

User is denied access to a certain message:

{
  "message": "Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4",
  "error": "forbidden",
  "status": 403,
  "cause": [ ]
}

Requested message does not exist:

{
    "message": "The specified message id does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

POST errors

Error by blocked message:

{
  "message": "You can not send the message because a mediation is in process.",
  "error": "blocked_conversation_send_message_forbidden",
  "status": 403,
  "cause": "blocked_by_mediation"
}

Error by shipping managed by Fulfillment (Mercado Libre):

Important:
This error only applies to Brazil.
{
    "message": "You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered.",
    "error": "blocked_conversation_send_message_forbidden",
    "status": 403,
    "cause": "blocked_by_fulfillment"
}

Message receiver does not belong to order: 403: Receiver does not belong to order {to.resource_id}.
Request without site_id: 400:The field 'to.site_id' is required.
site_id attribute is invalid: 400: The field 'to.site_id' has an invalid value.
Post without Json body: 400: A JSON body is required.
Message without ‘from’: 400: The field 'from' is required.
Request without access token: 400: Access token is required.
Access Token without application_id: 400: Application id is required.



GET messages by pack errors

User with no access to order: 403: User access token invalid for resource {resource_id}".
Request “limit” param must be greater than 0: 400: The limit param must be greater than 0.
“Offset” param is invalid: 400: Invalid offset param.
“Limit” param is invalid: 400: Invalid limit param.


GET attachments errors

Requested file could not be obtained: 500: File can not be accessed, try it later.


POST attachments errors

Problems when saving file: 500: File can not be saved, try it later.
Attachment empty or null: 400: File attached is empty.
File name cannot include characters such as: /, \ 400: File name cannot include characters like /, \ .
File size exceeds 25 Mb. File size: x 400: File attachment is bigger than 25 Mb.
Message exceeds allowed number of attachments: 25 400: The message exceeds the allowed number of attachments: 25.


PUT errors messages marked as unread

Invalid or empty message IDs:

{
    "message": "Messages id empty or invalid.",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Ineffective message IDs:

{
    "message": "The specified message id: a does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Message IDs that correspond to different orders:

{
    "message": "Not allowed messages from multiple orders",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Message not found in the server, try again in a few seconds:

{
    "message": "The message with id: a could not be retrieved from storage",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Next: Working with claims.