The 4theFile API is a REST-style API that uses simple standard technologies: HTTP requests with Basic auth, and XML or JSON response content. The API is designed primarily to allow developers and maintainers of web applications to easily provide an email interface to their applications without all the hassles involved in running an email server and parsing complex multi-part email messages, possibly with inline images, html, and attachments – 4theFile takes care of all that for you.

For more information, see the 4theFile API Overview

• A complete request includes an HTTP method, a url formed from the “endpoint”, the “resource”, and a response format specifier, and maybe some optional query parameters. PUT and POST methods may also require some input data in the request content body. The default endpoint is https://4thefile.com/api_v1

<method> <endpoint><resource>.<format>[?<querystring>]

Example: to GET the list of 4theFile Resources in Collection HJf56 that have “tag” 99 in XML format, the API resource is /collections/HJf56 and the whole request would look like:

GET https://4thefile.com/api_v1/collections/HJf56.xml?tag=99

• Each request must be authenticated with your username and apiKey (used as the Basic auth password). Most http clients and client libraries have support for Basic auth, so you don't need to be concerned with the details of the HTTP headers. For example, when using the Curl command line client you only need to add the -u option curl -u user:apiKey

• If your request is successful, you'll receive an HTTP “success” response code (usually 200 unless otherwise noted in the documentation for the resource) and the content in the format you specified (with appropriate MIME type, text/xml or application/json).

• If your request was not successful, you'll get a non-200 HTTP response code in the 300, 400, or 500 range, and some explanation in the response content with type text/plain. Check your response code! Typical non-200 response codes include 404 (means the resource you requested was not found), 403 (you don't have permission to perform the requested action on the resource), 401 (missing or incorrect Basic auth credentials).

• If the GET method is supported for a resource, HEAD is also supported

In all resource URLs below, segments that begin with : such as :collectionkey are placeholders, and you should substitute a valid collection key or resource key.

In each resource description we've provided a Curl command line which may be useful for exploring or testing the API. For actual integration with your application you'll probably want to use a language-specific HTTP library (such as libCurl, or LWP for perl). For more info on Curl and libCurl http://en.wikipedia.org/wiki/CURL

• method: GET /collections.format returns the list of collections owned by you.
• response formats supported: .xml, .json
• query parameters: none
• details and example

• Curl command line:

  curl -u jay:apikey http://4thefile.com/api_v1/collections.xml

• example xml response:

<?xml version="1.0" encoding="UTF-8"?>
<data>
  <collection_count>5</collection_count>
  <collections>
    <collection_api_link>http://4thefile.com/api_v1/collections/ESuVkqZF.xml</collection_api_link>
    <collection_name>4theFile demo</collection_name>
    <collectionkey>ESuVkqZF</collectionkey>
    <created>2010-06-02 14:01:45</created>
    <description>Used to demo how a shareable collection looks in 4theFile</description>
    <email>4thefiledemo</email>
    <moderated>9</moderated>
    <modified>2010-06-02 14:23:20</modified>
    <privacy>1</privacy>
    <resource_count>3</resource_count>
  </collections>
  <collections>
    <collection_api_link>http://4thefile.com/api_v1/collections/nV4wRRrx.xml</collection_api_link>
    <collection_name>ApplicationZ demo collection</collection_name>
    <collectionkey>nV4wRRrx</collectionkey>
    <created>2010-06-02 15:02:00</created>
    <description>This is a demo of a 4theFile collection as described
in the 4theFile Integration Center http://4theFile.com/pages/integration/</description>
    <email>applicationz</email>
    <moderated>9</moderated>
    <modified>2010-06-02 15:11:22</modified>
    <privacy>1</privacy>
    <resource_count>2</resource_count>
  </collections>
...
</data>

• field descriptions:
  • email: the email address for the collection (add @4thefile.com)
  • moderated: 1=none,3=retro-moderation(collection owner is notified of new submissions),9=closed(no more submissions)
  • privacy: 1=shareable, 5=private(anyone can submit but only owner can list collection contents)