Post-sale messages

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.

→Parameters description
↳Moderate shortened URLs
→Get messages by pack
→Get messages by ID
→Upload, save messages
→Create messages for a buyer
→Get attachment
↳Optionals parameters
↳Use modes
→Mark messages as read
→Check blocked messages
→Possible errors
↳Common errors
↳Errors to get message by ID
↳POST errors
↳GET messages by pack errors
↳GET attachments errors
↳POST attachments errors
↳PUT errors messages marked as unread

Parameters description

from: A message sender.
user_id: Id of user who sent message.
email: Email of user who sent message (order secure email).
name: Name of user who sent message.
to: A message recipient.
user_id: Id of user who received message.
email: Email of user who received message (order secure email).
text: Message text.
attachments: Attached files.
site_id: Mercado Libre (MLA, MLB, etc.) site.

We moderate shortened URLs by:

Bitly
Bl.ink
Polr
Rebrandly
T2M
TinyURL
URL Shortener by Zapier
Yourls

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.

To know the pack_id, you must obtain the “pack_id” field in the response of /marketplace/orders/order_id

If the pack id contains a null value, must take the order id by default.

The messages moderated by the counterpart will not be visible and the messages themselves will be visible.

Request:

curl -X GET https://api.mercadolibre.com/marketplace/messages/packs/$PACK_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/messages/packs/2000000089077943?access_token=$ACCESS_TOKEN&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.

Request:

curl -X GET https://api.mercadolibre.com/marketplace/messages/$MESSAGE_ID?access_token=$ACCESS_TOKEN

{
    "paging": null,
    "conversation_status": {
        "claim_ids": null,
        "shipping_id": null,
        "status": "",
        "status_date": "0001-01-01T00:00:00Z",
        "status_update_allowed": false,
        "substatus": null
    },
    "messages": [
        {
            "id": "e6bcab5ebdb34ab6b2a3cd21a314e214",
            "site_id": "MLM",
            "client_id": 123,
            "from": {
                "user_id": "523132944",
                "name": "TESTNICOCBT TESTNICOCBT"
            },
            "to": {
                "user_id": "441782523",
                "name": "Test Test"
            },
            "status": "available",
            "subject": null,
            "text": "More test message",
            "message_date": {
                "received": "2020-02-26T17:37:55Z",
                "available": "2020-02-26T17:37:55Z",
                "notified": null,
                "created": "2020-02-26T17:37:55Z",
                "read": null
            },
            "message_moderation": {
                "status": "clean",
                "reason": null,
                "source": "online",
                "moderation_date": "2020-02-26T17:37:55Z"
            },
            "message_attachments": [
                {
                    "filename": "471826944_ba20cdf4-26b4-4c21-a689-5eabe271ddb3.png",
                    "original_filename": "Imagen Perfil.png",
                    "type": "image/png",
                    "size": 536766,
                    "potential_security_threat": false,
                    "creation_date": "2020-02-26T17:37:56Z"
                },
                {
                    "filename": "523130418_10f6b123-5ec2-44dc-b611-e347098331a2.png",
                    "original_filename": "Imagen Perfil.png",
                    "type": "image/png",
                    "size": 536766,
                    "potential_security_threat": false,
                    "creation_date": "2020-02-26T17:37:56Z"
                }
            ],
            "message_resources": [
                {
                    "id": "2315686468",
                    "name": "packs"
                },
                {
                    "id": "523132944",
                    "name": "sellers"
                }
            ],
            "conversation_first_message": false,
            "text_translated": "Más mensaje de prueba"
        }
    ]
}

Upload, save messages

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 -X POST https://api.mercadolibre.com/marketplace/messages/attachments?access_token=$ACCESS_TOKEN

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 -X POST \ 'https://api.mercadolibre.com/marketplace/messages/attachments?access_token=ACCESS_TOKEN' \
  -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 -X POST https://api.mercadolibre.com/marketplace/messages/packs/$PACK_ID?access_token=$ACCESS_TOKEN

Example:

curl -X POST http://api.mercadolibre.com/marketplace/messages/packs/2315686468?access_token=$ACCESS_TOKEN \
  -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 -X GET https://api.mercadolibre.com/marketplace/messages/attachments/$ATTACHMENT_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?access_token=$ACCESS_TOKEN

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": []
}

Use modes

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

 
curl -X GET https://api.mercadolibre.com/marketplace/messages/unread?access_token=$ACCESS_TOKEN&user_id=$USER_ID

Response:
If the API response is satisfactory, you will get a JSON like this:

{
  "userId": 378136913,
  "results": [{
    "resource": "/packs/1977056109/sellers/378136913",
    "count": 1
  }]
}

In this response, you will see:

ID of user who made request (“user_id”).
Messages pending reading (“count”).
Each available order (“order_id”).

Finally, if there are no messages pending reading for all the user's orders or specific user's orders, or if the user specifies within the “orders_id” parameter those orders that are not part of it, the response will be like this:

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

Note:

This is a private resource, so if you make a call without access_token, you will get error 400.

Call without access token:

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

Mark messages as read

With the following GET you can mark the messages as read.

Request:

curl -X GET https://api.mercadolibre.com/marketplace/messages/packs/$PACK_ID/sellers/$SELLER_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/messages/packs/2000000089077943/sellers/415458330?access_token=$ACCESS_TOKEN

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"
                }
            ]
        },
        {
            "id": "2c92808469fea23a0169febdb0570000",
            "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:57:18.000Z",
                "available": null,
                "notified": null,
                "created": "2019-04-08T20:57:18.000Z",
                "read": "2019-04-08T20:57:22.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:57:19.000Z"
                }
            ],
            "message_resources": [
                {
                    "id": "2000000089077943",
                    "name": "packs"
                },
                {
                    "id": "415458330",
                    "name": "seller"
                }
            ]
        }
    ]
}

Check blocked messages

In order to reduce spam and unnecessary messages, within post-sales messages there is the possibility that some messages are blocked because:

The buyer decides to block the reception of messages.
The deadline for receiving messages has expired and will only be reopened if the buyer so decides.
There is a mediation between the buyer and the seller.
The purchase is made with Fulfillment and the package has not yet been delivered

Important:

This lock only applies to Brazil. In Argentina and Mexico it is not available.

The purchase has an ongoing measurement.

Via API you can find them under the status "Blocked" in a new section called "conversation":

Request:

curl -X GET https://api.mercadolibre.com/marketplace/messages/packs/$PACK_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/messages/packs/22175467?access_token=$ACCESS_TOKEN

Response:

{
    "paging": {
        "limit": 10,
        "offset": 0,
        "total": 4
    },
    "conversation_status": {
        "status": "blocked",
        "substatus": "blocked_by_buyer",
        "status_date": "2020-01-10T19:58:04.317Z",
        "status_update_allowed": false,
        "claim_ids": null,
        "shipping_id": null
    },
    "messages": [. . . ]
}

status: This field allows two values:

active: conversation is open for sending/receiving messages

- substatus: nullblocked: conversation is closed to sending/receiving messages

- substatus: Blocked_by_time

- substatus: Blocked_by_buyer

- substatus: Bloqued_by_mediation

- substatus: blocked_by_fulfillment

- substatus: Blocked_by_payment

status_date: Represents the date when conversation status was recorded.

Notes:

If the conversation has the blocked_by_payment substatus, it means the payment has not yet been made by the buyer or that it has not yet been impacted. This block is temporary until payment is made and it has impacted in the order. An order is not paid when it has any of the following status: payment_required, payment_in_process or partially_paid.
This payment update in the order may not be updated in the moment, so be prudent and wait at least 60 seconds to ensure that it has impacted in the order.

Possible errors

Common errors

Call without access token:

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

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.