XML-RPC to POP3 API specification

Andreas Bolka <andreas dot bolka at gmx dot net>

2001-08-23

Introduction

This document describes a relatively straight-forward approach to an XML-RPC to POP3 gateway. The goal is to enable POP3 access to all environments supporting XML-RPC.

This API also introduces a (to the XML-RPC community) - as far as I know - new authentication system. An authentication call returns a session id (called SID) which is used to authenticate successive calls. Commonly this is done by providing a SID param with successive calls. The following API approaches this problem by providing the authenticated functions under a method namespace containing the SID and therefore only accessible to the authenticated client during one session.

To use a service conforming to this API the process therefore is the following:

Authenticate using gateways.pop.session.login() and store the returned SID.
Given that the SID is "1324734" for example, call gateways.pop.1324724.stat to do a stat() call.

I could imagine that this imposes problems in clients for very static environments, please report any problems to <andreas dot bolka at gmx dot net>

This API has been implemented so far in xr2pop using Ruby and xmlrpc4r. If you support this API in an implementation, please let me know.

Method Overview

namespace: gateways.pop.session

login	Establishes and authenticates a POP3 session. (Related POP3 commands: USER, PASS)
login_apop	Establishes and (somewhat) securely authenticates a POP3 session using APOP. (Related POP3 commands: APOP)

namespace: gateways.pop.<sid>

logout	Tears down the POP3 session. (Related POP3 command: QUIT)
stat	Retrieves the message count and the mailbox size. (STAT)
list	Retrieves a list message numbers and their according message size. (LIST)
dele	Deletes a specified message. (DELE)
retr	Retrieves a specified message. (RETR)
retr64	Retrieves a specified message base64 encoded. (RETR)
uidl	Retrieves the UIDL of a specified message. (UIDL)
top	Retrieves the header and a given number of lines of a specified message. (TOP)

Method Details

gateways.pop.session.login

string login (
	string user,
	string pass,
	string popServer,
	int popPort
	)

Parameters

user: The username to authenticate with at the POP3 server
pass: The password to authenticate with at the POP3 server
popServer: The hostname of the POP3 server
popPort: The TCP port the POP3 server is listening at (usually 110)

Return value

A string containing a session id (sid). This sid is used to further identify this session.

Exceptions

Error Code	Condition
101	POP3 authentication failed

gateways.pop.session.login_apop

Works the same way as login but authenticates the user using the APOP authentication method instead.

gateways.pop.<sid>.logout

bool login ( )

Return value

A boolean beeing always true.

gateways.pop.<sid>.stat

struct stat ( )

Return value

A struct containing exactly two name-value elements

Name	Value
"count"	An integer representing the total messages in the mailbox
"size"	An integer representing the mailbox size

gateways.pop.<sid>.list

struct list ( )

Return value

A struct containing n name-value elements, mapping message numbers (integer) to the size (integer) of their according message.

gateways.pop.<sid>.dele

bool dele (
	int messageNumber
	)

Parameters

messageNumber: The number of the message to be deleted

Return value

A boolean beeing always true.

Exceptions

Error Code	Condition
201	The message with the given number does not exist.

gateways.pop.<sid>.retr

string retr (
	int messageNumber
	)

Parameters

messageNumber: The number of the message to be retrieved

Return value

A string containing the message.
WARNING: line-breaks will be encoded as CR which is not RFC822 conform.

Exceptions

Error Code	Condition
201	The message with the given number does not exist.

gateways.pop.<sid>.retr64

base64 retr64 (
	int messageNumber
	)

Parameters

messageNumber: The number of the message to be retrieved

Return value

Base64-encoded data containing the message.
WARNING: line-breaks will be encoded as CR which is not RFC822 conform.

Exceptions

Error Code	Condition
201	The message with the given number does not exist.

gateways.pop.<sid>.uidl

string uidl (
	int messageNumber
	)

Parameters

messageNumber: The number of the message whose UIDL is to be retrieved

Return value

A string containing the UIDL of the given message.

Exceptions

Error Code	Condition
201	The message with the given number does not exist.

gateways.pop.<sid>.top

string top (
	int messageNumber,
	int lines
	)

Parameters

messageNumber: The number of the message to be retrieved.
lines: The number of lines to be retrieved. with lines = 0 only the message headers will be retrieved, lines = n retrieves the headers and n lines of the message's body.

Return value

A string containing the requested part of the message.

Exceptions

Error Code	Condition
201	The message with the given number does not exist.

Copyright and disclaimer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.