Message management

→Parameters
→Get messages by order
→Get messages by pack
→Get messages by ID
→Create messages for a buyer
→Upload and save messages
→Get attachment


Parameters

message_id: Message id.
date_created: Date of creation.
date: Date a message is saved.
date_received: Date a message is received.
date_available:Date a message went through moderation.
date_notified: Date a message was notified to counterparty.
date_read: Date a message was read by counterparty.
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).
subject: Email subject.
text: Message text.
plain: Message plain text.
attachments: Attached files.
attachments_validations: Attachment validation.
invalid_size: If attachment size is invalid.
invalid_extension: Invalid attachment extension.
internal_error: Internal error.
site_id: Mercado Libre (MLA, MLB, etc.) site.
resource: Corresponding to order it pertains to (orders).
resource_id: Order ID.
status: Message status.
moderation_status: Message moderation status

  • clean
  • rejected
  • pending: for cases that moderation is in process.
  • non_moderated: for old cases that moderation not apply moderation.

moderation.date_moderated: Date the moderation information impacted.

moderation.source Moderation mode.

moderation.reason Reason why the message was moderated. Currently, this moderation may be due to inappropriate language (OUT_OF_PLACE_LANGUAGE), social networks link (SOCIAL_NETWORK_LINK), shortened links (LINK_SHORT_URL) or be an automatic integrator message (AUTOMATIC_MESSAGE).


Get messages by order

Important:
For MLA and MLC use the check messages by pack.

To get the messages of a particular order you will have to make a query associating the order_id:

Request:

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

Example:

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

Response;


{
    "paging": {
        "limit": 10,
        "offset": 0,
        "threshold": 1000,
        "total": 1
    },
    "results": [
        {
            "message_id": "d13a11809dac44d497d829e9bbbc78ae",
            "date_received": "2019-07-04T20:50:02.124Z",
            "date": "2019-07-04T20:50:02.124Z",
            "date_available": "2019-07-04T20:50:02.124Z",
            "date_notified": "2019-07-04T20:51:33.471Z",
            "date_read": null,
            "from": {
                "user_id": "419059118",
                "email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
                "name": "Test"
            },
            "to": [
                {
                    "user_id": "419067349",
                    "email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com"
                }
            ],
            "subject": "Produto Teste - Não Ofertar",
            "text": {
                "plain": "Olá, tudo bem?"
            },
            "attachments": [],
            "attachments_validations": {
                "invalid_size": [],
                "invalid_extension": [],
                "forbidden": [],
                "internal_error": []
            },
            "site_id": "MLB",
            "resource": "orders",
            "resource_id": "2053577644",
            "status": "available",
            "moderation": {
                "status": "clean",
                "date_moderated": "2019-07-04T20:50:02.177Z",
                "source": "online"
            },
            "conversation_first_message": true
        }
    ],
    "conversation": {
        "status": "active",
        "status_date": null,
        "substatus": null,
        "is_blocking_allowed": false
    }
}

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 / messages.

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

If the pack id contains a null value, must take the order id by default, keeping the resource /packs in the API request.

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

Important:
When request /messages/packs/pack_id/sellers/seller_id the messages will be marked as read. In case you don't want to mark them as read, perform the GET with the mark_as_read = false parameter and the query will be: /messages/packs/pack_id/sellers/seller_id?mark_as_read=false.
Remember that the rest of the resources will not mark the messages as read.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID

Example:

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

Response;


{
   "paging":{
      "limit":10,
      "offset":0,
      "total":3
   },
   "conversation_status":{
        "path": "/packs/2000000089077943/seller/415458330",
        "status": "active",
        "substatus": null,
        "status_date": "2020-12-05T20:01:46.000Z",
        "status_update_allowed": false,
        "claim_id": null,
        "shipping_id": null
    },
   "messages":[
      {
         "id":"fd1d2e37ad004ede9e0bf25d1215002d",
         "site_id":"MLB",
         "client_id":123456789,
         "from":{
            "user_id":"123456789000",
            "email":"test@test.com.br",
            "name":"User Test"
         },
         "to":{
            "user_id":"2332423234",
            "email":"juliotest@test.com",
            "name":"Julio Test"
         },
         "status":"available",
         "subject":null,
         "text":"Mensaje de test",
         "message_date":{
            "received":"2020-12-05T20:01:46.000Z",
            "available":"2020-12-05T20:01:46.000Z",
            "notified":"2020-12-05T20:01:46.000Z",
            "created":"2020-12-05T20:01:46.000Z",
            "read":null
         },
         "message_moderation":{
            "status":"clean",
            "reason":null,
            "source":"online",
            "moderation_date":"2020-12-05T20:01:46.000Z"
         },
         "message_attachments":null,
         "message_resources":[
            {
               "id":"000011122344",
               "name":"packs"
            },
            {
               "id":"475684066",
               "name":"sellers"
            }
         ],
         "conversation_first_message":false
      }
   ],
   "seller_max_message_length":350,
   "buyer_max_message_length":3500
}
Note:
At the response end, you can see the maximum number of characters that the seller can send (seller_max_message_length).

Errors

Status Error Message
403 User access token invalid for resource {resource_id} User without access to order
400 The limit param must be greater than 0 The “limit” request param must be greater than 0
400 Invalid offset param Invalid “Offset” param
400 Invalid limit param Invalid “limit” param

Get messages by ID

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

Note:
Please include the “X-Pack-Format” header in the request: true to get the updated answer. If you don´t send it, you will continue to receive the old response based on the order.

Request:

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

Response example without header:

{
  "message_id": "0033b582a1474fa98c02d229abcec43c",
  "date_received": "2016-09-01T05:15:25.821Z",
  "date": "2016-09-01T05:15:25.821Z",
  "date_available": "2016-09-01T05:15:25.821Z",
  "date_notified": "2016-09-01T05:17:42.945Z",
  "date_read": "2016-09-01T21:31:19.606Z",
  "from": {
    "user_id": "123456789",
    "email": "userfrom.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
    "name": "User from"
  },
  "to": [
    
      "user_id": "123456780",
      "email": "userto.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
    
  ],
  "subject": "Test Item subject",
  "text": {
    "plain": "Ejemplo de texto"
  },
  "attachments": [
    {}
  ],
  "attachments_validations": {
    "invalid_size": [
    ],
    "invalid_extension": [
    ],
    "forbidden": [
    ],
    "internal_error": [
    
  },
  "site_id": "MLA",
  "resource": "orders",
  "resource_id": "1234567871",
  "status": "available",
  "moderation": {
  	"status": "clean",
      "date_moderated": "2019-03-13T09:34:26.450-04:00",
      "source": "online"

  
}

Response example with header:

{
    "paging": null,
    "conversation_status": null,
    "messages": [
        
            "id": "2c9380846a6fc814016a6fd38fe00007",
            "site_id": "MLA",
            "client_id": 1,
            "from": {
                "user_id": "391302538",
                "email": "fernanda.giustozzi+391302538@mercadolibre.com",
                "name": "Test Test"
            },
            "status": "available",
            "text": "newMessage",
            "message_date": {
                "received": "2019-04-30T19:58:17.000Z",
                "available": "2019-04-30T19:58:17.000Z",
                "notified": null,
                "created": "2019-04-30T19:58:17.000Z",
                "read": "2019-04-30T20:24:48.000Z"
            },
            "message_moderation": {
                "status": "clean",
                "reason": null,
                "source": "online",
                "moderation_date": "2019-04-30T19:58:17.000Z"
            },
            "message_attachments": [
                
                    "filename": "391302538_b6498e76-5af0-4206-aaeb-2aa6e754263e.jpg",
                    "original_filename": "319176.jpg",
                    "type": "image/jpeg",
                    "size": 661635,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-30T19:58:17.000Z"
                
            ],
            "message_resources": [
                
                    "id": "2000000094354573",
                    "name": "packs"
                },
                
                    "id": "391302235",
                    "name": "sellers"
}

Errors

Status Error Message
403 Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4 User without access to a certain message
400 The specified message id does not exists The specified message does not exist
404 The message with id: a could not be retrieved from storage The message with id: a could not be retrieved from storage. Try again in a few seconds.


Create message for a buyer

To send a message to your buyer, you must add the user_id and the seller's email in the “from” of the message. Also, remember that you have the 350 characters limit.

Remember that we accept those characters included in the ISO-8859-1 latin1 standard and the emoticons from this list.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330"&application_id=$APPLICATION_ID
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: 167b4f47-cb87-2b27-2a3c-cfb012df9314' \
  -H 'x-client-id: 8794217632667367' \
  -d '{
"from" : {
"user_id": "415458330",
"email" : "test"
},
"to": {
		"user_id" : "415460047"
},
   	"text": "Test message ToUserId 2",
   	"attachments": ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf"]
}'
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 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>".

Errors

Status Error Message
400 The text has character/s that is/are not supported. The message content is too long, max characters allowed are 350
400 The message content is too long, max characters allowed are 350 When you send an unsupported character, for example: UTF-8.
403 You can not send the message because a mediation is in process Blocked message error. This error only applies to Brazil.
403 You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered Shipping error managed by Fulfillment (Mercado Libre)
403 Access denied for user {from.user_id} to order {to.resource_id} The user “from” doesn´t have access to the order
403 Receiver does not belong to order {to.resource_id} The recipient of the message does not belong to the order
400 The field 'to.user_id' is required Message without receiver (need to add "to")
400 Invalid ‘to’ user id Invalid “to” user id
400 Sender and received must not be equals The user “from” and “to” are equal
400 The field 'to.email' must be a secure email If the user_id is 0 and the email not be a secure_email
400 The field 'to.resource' is required The field 'to.resource' is required
400 Invalid field 'to.resource' Invalid resource attribute
400 The field 'to.site_id' is required Request without site_id
400 The field 'to.site_id' has an invalid value Invalid ite_id attribute
400 A JSON body is required Post without Json body
400 The field 'from' is required Message without ‘from’
400 Access token is required Request without access token
400 Application id is required Access token without application_id

Upload and 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:

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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.

Example:

curl -X POST \
  'https://api.mercadolibre.com/messages/attachments' \
  -H 'Authorization: Bearer $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"
}

Status Error Message
500 File can not be saved, try it later Problemas al almacenar el archivo
400 File attached is empty Empty or null attachment
400 File name cannot include characters like /, \ File name cannot include characters like /, \
400 File attachment is bigger than 25 Mb. File attachment is bigger than 25 Mb.
400 The message exceeds the allowed number of attachments: 25 The message exceeds the allowed number of attachments: 25

Get attachment

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

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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:

Error

Status Error Message
500 File can not be saved, try it later File can not be saved, try it later

Next: Pending messages.

or register to recieve the latest news about our API