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 name

Obligation

Definition/Value

folder

Optional

The folder to search for messages. If not specified, the INBOX folder is searched.

limit

Optional

Specify the number of messages to return.

recent

Optional

Orders the results with the most recent listed first. This setting only applies if limit is also specified.

unseen

Optional

Return 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.

user

Required

The 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 name

Obligation

Description/Value

count

Returned if success = true

The number of messages returned in the messages list.

error

Returned if success = false

A text string that explains the error.

error_number

Returned if success = false

A number that represents the error.

messages

Returned if success = true

A 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.

success

Always returned

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