Messaging after sale

The messing API resource will enable you to get messages from a specific order, create new messages in the system, and send or receive attachments.
Let’s see how you can use it!

Contents:

Parameters description

message_id Message id
date_created Date of creation
date Date a message is saved
date_received Date a message is received
date_availableDate 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

Get messages

To get messages from a specific order, you should associate the order_id with this resource via GET.

Call:

GET ".../messages/orders/$order_id"

Example:

 curl -X GET “https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN”

Possible extra parameters:

These parameters can be used to determine the number of messages recovered by GET.

&limit={límite} >> positive integer

Example:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10”

&offset={compensación} >> positive integer

Example:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10&offset=1”

Response:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 270
    },
    "results": [
        {
            "_id": "43b450d6bd3f47fb94394041b26c519f",
            "message_id": "43b450d6bd3f47fb94394041b26c519f",
            "date_received": "2016-11-07T15:03:14.978Z",
            "date": "2016-11-07T15:03:14.978Z",
            "date_available": "2016-11-07T15:03:14.978Z",
            "date_notified": "2016-11-07T15:05:50.179Z",
            "date_read": "2016-11-08T22:43:17.767Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            "moderation_status": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "client_id": 1000
        },
        {
            "_id": "37befd545a2d436f89e672b33990ef8b",
            "message_id": "37befd545a2d436f89e672b33990ef8b",
            "date_received": "2016-11-07T14:56:02.500Z",
            "date": "2016-11-07T14:56:02.500Z",
            "date_available": "2016-11-07T14:56:02.500Z",
            "date_notified": "2016-11-07T14:57:46.659Z",
            "date_read": "2016-11-07T15:19:08.967Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            "moderation_status": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "client_id": 1000
        }
    ]
}

Notes:

  • Per each sale from a buyer you will get a different masked email. That is, if the same buyer purchases you two different products at different times, each sale will generate an email.
  • The buyer’s contact mails will be viewed masked so the number of characters (between 55 and 60) will increase.

Get messages by ID

Request:

GET “https://api.mercadolibre.com/messages/{message_id}?access_token=$ACCESS_TOKEN”

Response Example:

{
  "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": "non_moderated"
  }
}

Create messages

In case of from seller, order seller.id will go in from.user_id.

Call:

POST “https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID” 

Note: The “application_id” is only required when the Access Token does not have the APP ID embedded.

Example:

curl -i -X POST -H "Content-Type: application/json" -H “X-Client-Id: {application id}” -d
'{
    "from": {
        "user_id": 123435,
    },
    "to": [
        {
            "user_id": 9191923,
            "resource": "orders",
            "resource_id": 2223213,
            "site_id": "MLA"
        }
    ],
    "text": {
        "plain": "Plain text message here"
    }
}’ https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID

Note: The attachments attribute is obtained from the attachment POST response. (See attachments section).

Send attachment

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.

Call:

POST “https://api.mercadolibre.com/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 5 MB size.
  • You can exchange pictures, instruction manuals, invoices, and any other attachments of up to 5MB in JPG, PNG, PDF and TXT format.

Example:

curl-i-XPOST-H"Content-Type: multipart/form-data"-F"file=@/home/user/file""https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN"

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"
}

Get attachment

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

Call:

GET “https://api.mercadolibre.com/messages/attachments/{attachment_id}?access_token=$ACCESS_TOKEN” 

Example:

https://api.mercadolibre.com/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": []
}



To conclude, following all these steps, the POST will be like this…

Example:

{
    "from": {
      "user_id": 123455677
    },
    "to": [
        {
            "user_id": 72345286,
            "resource": "orders",
            "resource_id": 1234567671,
            "site_id": "MLA"
        }
    ],
    "text": {
      "plain" : "Mensaje de pruebas"
    },
  	"attachments" : ["76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png" ]


}

Response:

[
    {
        "message_id": "d2345e6e7bb844469ae79623018223af",
        "date_received": "2016-11-14T20:46:49.678Z",
        "date": "2016-11-14T20:46:49.678Z",
        "date_available": "2016-11-14T20:46:49.678Z",
        "date_notified": null,
        "date_read": null,
        "from": {
            "user_id": "123455677",
            "email": "userseller.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
            "name": null
        },
        "to": [
            {
                "user_id": "72345286",
                "email": "userbuyer.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
            }
        ],
        "subject": null,
        "text": {
            "plain": "Mensaje de pruebas"
        },
        "attachments": [
            {
                "size": "103584",
                "type": "image/png",
                "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                "filename": "76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png",
                "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
            }
        ],
        "attachments_validations": null,
        "site_id": "MLA",
        "resource": "orders",
        "resource_id": "1125027671",
        "status": "available",
        "moderation": {
            "status": "non_moderated"
        }
    }
]

Mark messages as read

With this PUT call, you can mark messages as read in Mercado Libre providing the IDs you want to read in the URL.

Note: Messages should be separated by comma (,); otherwise, they will not be recognized as different messages.

Call:

PUT /messages/mark_as_read/:messages_id

Example:

https://api.mercadolibre.com/messages/mark_as_read/id1,id2,id3?access_token=$ACCESS_TOKEN

Response:

{
    "message": "Messages marked as read successfully",
    "status": 200
}

Possible errors

Common errors

Request 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

Message without receiver (“to” is missing):
400: The field ‘to.user_id’ is required

User id “to” invalid:
400: Invalid ‘to’ user id

User “from” and “to” are the same:
400: Sender and received must not be equals

User “from” is denied access to order:
403: Access denied for user {from.user_id} to order {to.resource_id}

If user_id is 0 and email is not a secure_email:
400: The field ‘to.email’ must be a secure email

Message receiver does not belong to order:
403: Receiver does not belong to order {to.resource_id}

“Resource” attribute is not found:
400: The field ‘to.resource’ is required

Resource attribute is invalid:
400: Invalid field ‘to.resource’

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 order 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 5 Mb. File size: x
400: File attachment is bigger than 5 Mb.

Message exceeds allowed number of attachments: 5
400: The message exceeds the allowed number of attachments: 5

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



To get more information about how to use this service without logging out Mercado Libre, click here.


Next topic:
Subscribe to our feeds.

Please rate this