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
        ↳Moderate shortened URLs
    →Get messages by pack
    →Get messages by ID
    →Upload, save messages
    →Create messages for a buyer
    →Get attachment
    →Messages pending reading
        ↳Optionals parameters
    →Pending messages filtered by resource
        ↳Use modes
    →Mark messages as read
    →Review 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

    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) or shortened links (LINK_SHORT_URL).


    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 / 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:
    This way of working will be productive on different dates and will have a month of backwards compatibility from each corresponding date:
    - Mercado Libre Chile: productive on July 10.
    - Mercado Libre Argentina: productive on July 15.
    - Mercado Livre Brasil: productive on August 21.
    - Mercado Libre Mexico: productive on September 23.
    - Mercado Libre Colombia, Venezuela, Peru and Uruguay: productive on October 2.

    Call:

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

    Example:

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

    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": "MLA",
                "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": "MLA",
                "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"
                    
                
            
        
    }
    Note:
    Will not longer have the buyer’s masked email.

     

    Get message 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.

    Call:

    curl -X GET https://api.mercadolibre.com/messages/$MESSAGE_ID?access_token=$ACCESS_TOKEN
    Header:
    key: “X-Pack-Format”
    value: true

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


    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.
    Call:

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

    To send a message to your buyer, you must add the user_id and the seller's email in the “from” of the message.


    Call:

    curl -X POST https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID?access_token=$ACCESS_TOKEN

    Example:

    curl -X POST \  'https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?access_token=$ACCESS_TOKEN"&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.

    Get attachment

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

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

    Example:

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


    Messages pending reading

    This option will let you get in Mercado Libre messages pending reading from all the existing orders or just specific orders. You can also define the user role in each case, whether buyer or seller. To obtain the above mentioned information, make a GET as shown below. Call:

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

    Optionals parameters

    -“role”: “buyer”/”seller”


    Pending messages filtered by resource

    Call:

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

    Example:

    curl -X GET https://api.mercadolibre.com/messages/unread/packs/1234/sellers/2345?access_token=$ACCESS_TOKEN

    Response:

    {    
    "user_id": 2345, 
    "results": [ { 
    "resource": "/packs/1234/sellers/2345", "count": 1 
    } ] 
    }
    

    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/messages/unread?access_token=$ACCESS_TOKEN&role=$ROLE

    Possible values ​​for ROLE are “buyer” or “seller”.

    Note:
    In case not specifying a role or that it is invalid (other than “buyer” or “seller”), the resource will return all cases. 

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

    {
    	"user_id": 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 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:

    curl -X PUT https://api.mercadolibre.com/messages/mark_as_read/$MESSAGES_ID?access_token=$ACCESS_TOKEN

    Example:

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

    Response:

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


    Review blocked messages

    In order to reduce spam and unnecessary messages, messages can be blocked within post sale messaging because:

    • The buyer has blocked message delivery.
    • The deadline for receiving messages has expired and will only be reopened if the buyer so decides.
    • There is mediation between the buyer and the seller.
    • The purchase is made with Fulfillment and the package has not yet been delivered or has a measurement in progress.

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

    https://api.mercadolibre.com/messages/orders/$RESOURCE_ID?access_token=$ACCESS_TOKEN

    Response:

    {
      "paging": {...},
      "results": [{...},{...}],
      "conversation": {
    "status": "blocked",
    "substatus": "blocked_by_buyer",
          "status_date": "2017-05-26T13:17:23.511-04:00"
       }
    }

    status: This field allows two values:

    • active: conversation is open for sending/receiving messages.
    • substatus: null
    • blocked: conversation is closed to sending/receiving messages.
    • substatus: Blocked_by_time.
    • substatus: Blocked_by_buyer.
    • substatus: Bloqued_by_mediation.
    • substatus: Blocked_by_fulfillment.

    status_date: Represents the date when conversation status was recorded.


    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):

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

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

    Next topic: Receive notifications.

Be part of our community