-
Notifications
You must be signed in to change notification settings - Fork 0
REST API
#REST API The REST API provides the access to all emails received by the SMTP server and also provides a mechanism to delete stored messages.
It's important to understand how psmtp stores emails in order to understand how one can filter and access them via this REST API.
#Mail Storage Since psmtp is not a real SMTP server, it doesn't really care who an email is addressed to since it will never actually attempt to deliver it anyway. Instead all received email is just stored by psmtp in a database. What psmtp does care about is which host is sending the email through psmtp.
Every email received by psmtp is associated with the IP address of the machine that sent it. In order to filter messages you must know where they came from. In order to download any specific message you not only need to know its internal message id number, you also must know from which hostname/IP address the message was sent from. Every host that sends an email through psmtp has its own distinct, "private" mailbox. The REST API will only find messages or give access to messages if the requester also knows where it came from.
This design allows a single psmtp instance to be used by any number of testers simultaneously. Since you can only act on the messages associated with the IP address you provide, you can freely delete messages as needed and not worry about possibly messing up someone else's testing. This also reduces the number of psmtp instances a QA environment should need to deploy. As a matter of fact, one single psmtp instance should be enough for most development and/or QA environments.
All URIs in this document would need to be appended to the app's deployed context in order to construct the full URL one would request. For example, the endpoint /api/messages as described here would be accessible via the URL http://<host>:<port>/<context>/api/messages (i.e. http://localhost:8080/psmtp/api/messages).
The API is rather small, as a matter of fact there is only one resource exposed by the API, messages, and one subresource of messages, attachments. You can access a list of available messages (optionally filtered), delete all messages (within client scope), download a single message or delete a single message. And then you can access any attachments associated with a message.
All API requests must contain a query parameter clnt. This is the hostname or IP address of the host that sent the message(s) you are interested in. This is known as the client scope parameter. Only messages received from this client host are considered when filtering or downloading. A valid message id request (/api/messages/{id}) that includes the wrong client scope will respond with a 404 Not Found error even though the message is stored in psmtp's database. You cannot provide more than one client scope to access the messages from multiple sources. You can specify the hostname instead of an IP address, but be careful about doing this. Using hostnames for client scope relies on the DNS resolving of your systems to be correct. Also, if a hostname resolves to more than one IP address then there's no guarantee which address psmtp will use (it will not use them all since a client scope can only be one address per request). For the most reliable results, use IP addresses instead of hostnames.
Successful return code: 200Content-Type: application/json-
{addr}:The client scope (see above) -
{filter}:A single constraint used to filter the list of returned messages; multiple filters can be provided in a single query (details)
Retrieve a list of all messages within the given client scope that match all given filters. If no filters are provided then simply return a list of all messages within the given client scope.
If no messages match the conditions then a 404 Not Found error is returned otherwise the response is a JSON array of JSON objects that have the following format:
{
id: int,
url: string
to: array
cc: array
bcc: array
_for: array
_attachments: int
_attachmentInfo: array
sent: *date*
from: string
}
The id field is an integer and is the unique internal message id that can be retrieved via the /api/messages/{id} endpoint. The url field is the complete URL that can be used to download the corresponding MIME message stream.
The other fields are the minimum included with each message returned. In addition, all email headers are also returned, but the specifics of the email headers depend on the content sent by the sending applcation (under test). The fields shown above are guaranteed to be included with every email.
The format for a filter is documented in detail here.
Successful return code: 204Content-Type: N/A-
{addr}:The client scope (see above)
Deletes all stored messages for the given client scope.
Successful return code: 200Content-Type: application/octet-stream-
{id}:The message id to retrieve -
{addr}:The client scope (see above)
Returns the complete MIME message binary stream of the given message id for the given client scope. If no such message exists for the given id and client scope combo then a 404 Not Found error is returned.
On success, the returned data is the complete MIME message binary stream suitable for parsing with your favourite MIME message library. NOTE: Any BCC recipients included in the original message delivery will be included in the returned message (i.e. if necessary, a BCC header will be reattached to the message before being returned).
Successful return code: 204Content-Type: N/A-
{id}:The unique message id to be deleted; retrieved from the/api/messagesendpoint -
{addr}:The client scope (see above)
Delete a single message identified by id and client scope. Returns 204 (and no content) on success or 404 Not Found if the message identified by the id and scope does not exist.
Successful return code: 200Content-Type: application/octet-stream-
{id}:The unique message id for the email -
{fname}:The name of the file attachment to download -
{addr}:The client scope (see above) - Added in v0.2.0
Downloads the full, raw binary data of the given attachment for the given message.