get_user_messages

The get_user_messages method returns a list of user messages in a specified folder.

Syntax

{
    <credentials object> 
    "user": <mailbox_name>, 
    "folder": <folder_name>
}

Request fields for get_user_messages

The following fields can be used in the get_user_messages method:

Field nameObligationDefinition/Value
folderOptionalThe folder to search for messages. If not specified, the INBOX folder is searched.
limitOptionalSpecify the number of messages to return.
recentOptionalOrders the results with the most recent listed first. This setting only applies if limit is also specified.
unseenOptionalReturn a list of only those messages that have been delivered to the user, but have not yet been displayed in the user's mail client or through Webmail.
userRequiredThe user's account name.

Specifying a combination of unseen, limit, and recent would be useful as a follow-up call to the user_notify method for a Reseller portal, for example, you could check to see if there are new messages, and then fetch the five most recent message headers to display to the end user.

Response fields for get_user_messages

The following fields may be returned in response to the get_user_messages
method:

Field nameObligationDescription/Value
countReturned if success = trueThe number of messages returned in the messages list.
errorReturned if success = falseA text string that explains the error.
error_numberReturned if success = falseA number that represents the error.
messagesReturned if success = trueA list of the messages in the specified folder. Includes the following information for each message listed:

headers—A hash containing the message headers and their values.

id—the message id. The id number is used by the move_user_messages method.
successAlways returnedIndicates whether the request was successful or not. Allowed values are true and false.

Examples for get_user_messages

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "pencil75"
  },
  "user": "[email protected]",
  "folder": "Trash"
}

Response

{
  "success": true,
  "messages": [
    {
      "headers": {
        "INTERNALDATE": [
          1325879547
        ],
        "content-disposition": [
					"inline" 
        ],
        "content-type": [
          "text/plain; charset=us-ascii"
				], 
        "date": [
          "Fri Jan  6 19:52:27 2012"
        ],
        "subject": [
          "Welcome!"
        ], 
        "from": [
					"Mister Manager <[email protected]>" 
        ]
			},
			"id": "U2FsdGVkX1/1NoyVE6nnFbezjndojMCc+wKwHMv6alN1D6+ANvZ0sJovSQ8wpPPW7Gb0iv Du/6v0fJWAIrR2S0"
    }, 
    {
			"headers": {
  			"INTERNALDATE": [
    			1326918028
  		],
  		"content-disposition": [
    		"inline"
  		],
  		"content-type": [
    		"text/plain; charset=us-ascii"
  		],
  		"date": [
        "Wed Jan 18 20:20:28 2012"
      ],
      "subject": [
        "Please empty the fridge!"
      ],
			"from": [
				"Mister Manager <[email protected]>"
			] 
		},
    "id": "U2FsdGVkX181ebK9176pd1Iyfsn8Cad5r3lJF9Dj/dskhl0kLi4wdf2nC2n/qgGZ16yK/J EOs42nSuEaWgyy/ZG
    }, 
    {
			"headers": {
  			"return-path": [
    			"[email protected]"
  			],
  			"subject": [
    			"Thought you might find this interesting"
				], 
        "date": [
    			"Wed, 18 Mar 2009 15:17:16 -0400"
  			],
  			"domainkey-signature": [
          "a=rsa-sha1; c=nofws; d=bigmail.com; s=gamma; h=mime- version:date:message-id:subject:from:to:content-type; b=iTWQ0kqo3VI9vtYLylGLjEFTibCMnQXCnSAJub8G1QwYh6UFQWtsssjA6brVeBsMQm OZ5s7fOD9Tjq5hm52lw2O5VEdM+l8UtxzUIyVbabTbJBinvQlZXuHM1lEhDLJWK+mr6R j5URFTFMsLo1EV38iOQPS+y8g3xSLbZZtkWYs="
        ],
        "INTERNALDATE": [
          1326918153
        ],
				"content-type": [
					"multipart/mixed; boundary=0016e64601e61d626b0465698817"
				],
        "to": [
          "<[email protected]>"
        ],
        "dkim-signature": [
        	"v=1; a=rsa-sha256; c=relaxed/relaxed; d=bigmail.com; s=gamma; h=domainkey-signature:mime-version:received:date:message- id:subject :from:to:content-type; bh=alRvlC+CVwx+e7ngmXH4/KHUuXpinJk5JMA1wqoZAss=; b=nyeK2yYuuV0pQrKXdqrPAwO1wskMLNZ9byvxH2IknVuaS2bHHt364lv1FrZQsvVRSk IO8GZi/5GySlUHpQhyUONJhaol/w1/nCZcf/0VAgE5bcWwHSfl99Dks7ymY6Gw82uShz /wwBuhKEijuskGloKojyXEzBo0JHPrGl6Bv7g="
        ], 
        "from": [
					"Joseph Joeson <[email protected]>" 
          ],
        	"mime-version": [
          	"1.0"
        	],
        	"received": [
          	"by 10.220.95.68 with SMTP id 
c4mr1102844vcn.25.1237403836440; Wed, 18 Mar 2009 12:17:16 -0700 (PDT)"
				],
        "message-id": [
					"<[email protected]
om>"
				]
			},
      "id": "U2FsdGVkX18701M4DRzWHCAPojAWZnk/vumzyS5NKi9K8xjM3XA3WGJk3/mrHWl18I12ca /X/rGSnhmwja+Yl4emx
    } 
  ],
  "count": 3 
}