APPLICATION API

The service API is implemented as vanilla XML over HTTP using all four verbs (GET/POST/PUT/DELETE). Every resource, like Users, Folders, or Rules, has their own URL and are manipulated in isolation. In other words, we've tried to make the API follow the REST principles as much as we can.

Authentication is managed using HTTP authentication (only “Basic” is supported right now). Every request must include the Authorization HTTP header. Use the API token as the username, and “X” (or some otherwise bogus text) as the password (only the API token is used for authenticating API requests). Example with Curl:

curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
  -u 653638dc733afce75130303fe6e6010f63768af0:X \ 
  -d '<request>...</request>' https://secure.replygrid.net/account/api.php/command

The API token can be found under Maintenance > Users area under “Authentication token”. You may use an existing user, or create a new user for specific API access. Keep in mind that access to resources of via API is the same as the Access Rights of the user associated with the API Token.

Be sure to set both the 'Content-Type' and 'Accept' headers to 'application/xml' to identify the request and response format. Example with Curl:

curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
  -u hoodlum:up2n0g00d \
  -d '<conditions>...</conditions>' \
  https://secure.replygrid.net/account/api.php/1/rules/2/update_contitions

If a request succeeds, it will return a status code in the 200 range and often, an XML-formatted response. Note that, in general, if a request causes a new record to be created (like a new user, or folder, etc.), the response will use the “201 Created” status. Any other successful operation (like a successful query, delete, or update) will return a 200 status code.

If a request fails, a non-200 status code will be returned, possibly with error information in XML format as the response's content. For instance, if a requested record could not be found, the HTTP response might look something like:

HTTP/1.1 404 The record could not be found
Date: Thu, 16 Mar 2006 17:41:40 GMT
...

You can perform up to 5 requests per second from the same IP address for the same account. If you exceed this limit, you'll get a 503 response. Check the Retry-After header for the punishment duration (currently 20 seconds).

To make things easier to understand, the following notation is used:

• #{text}: Indicates text that should be replaced by your own data
• …: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type.

GET …/api.php/sections

Returns all accessible sections.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sections>
  <section>
    <section_id>2</id>
    <name>My Company</name>
    ...
  </section>
  <section>
    ...
  </section>
  ...
</sections>

This API is only available to Administrators or Super Administrators

GET …/api.php/users/#{section_id}

Returns all users for the section specified.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<users>
  <user>
    <user_id>4</user_id>
    <section_id>1</section_id>
    <user_name>tobie.champagne</user_name>
    <first_names>Tobie</first_names>
    <last_name>Champagne</last_name>
    <email>tobie@company.com</email>
    <is_active>1</is_active>
    <type>U</type>
    <last_visit_date>2008-07-11 14:54:52</last_visit_date>
    <folders>
      <folder>
        <folder_id>1</folder_id>
        <name>Returns</name>
      </folder>
      <folder>
        <folder_id>4</folder_id>
        <name>Spam</name>
      </folder>
      <folder>
        <folder_id>5</folder_id>
        <name>Inbox</name>
      </folder>
    </folders>
  </user>
  <user>
    ...
  </user>
</users>

POST …/api.php/users/#{section_id}/add

Add users indicated by the submitted XML data.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user_add>
  <user>
    <user_name>albert.camus</user_name>
    <password>abc123</password>
    <first_names>Albert</first_names>
    <last_name>Camus</last_name>
    <email>albert@company.com</email>
    <is_active>1</is_active>
    <html_editor>1</html_editor>
    <delete_emails>1</delete_emails>
    <type>U</type>
    <folders>
        <folder_id>1</folder_id>
        <folder_id>4</folder_id>
        <folder_id>5</folder_id>
    </folders>
  </user>
  <user>
   ...
  </user>
</user_add>

Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error.

POST …/api.php/users/#{section_id}/change

Changes the user information indicated by the submitted XML data. Tags in the <change>…</change> block are optional, and only the ones provided will be changed.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user_change>
  <user>
    <user_name>tobie.champagne</user_name>
	<change>
		<password>xxyy12</password>
		<first_names>Tobias</first_names>
		<last_name>Chamignone</last_name>
		<email>tobiec@company.com</email>
		<is_active>0</is_active>
		<html_editor>0</html_editor>
		<type>U</type>
		<delete_emails>0</delete_emails>
		<folders>
			<folder_id>2</folder_id>
			<folder_id>7</folder_id>
		</folders>
	</change>
  </user>
  <user>
   ...
  </user>
</user_change>

Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error.

GET …/api.php/folders/#{section_id}

Returns folders for the section specified that the user associated with the token has access to.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<folders>
  <folder>
    <name>Returns</name>
    <folder_id>1</folder_id>
    <section_id>1</section_id>
    <email>returns@company.com</email>
    <from_email>support@company.com</from_email>
    <email_count>10</email_count>
    <read_count>7</read_count>
    <unread_count>2</unread_count>
    <priority_count>1</priority_count>
  </folder>
  <folder>
    ...
  </folder>
</folders>

This API is only available to Administrators or Super Administrators

GET …/api.php/rules/#{section_id}

Returns a list of rules for a given section.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rules>
  <rule>
    <rule_id>2</rule_id>
    <title>ProCurve</title>
    <is_active>1</is_active>
    <rank>8</rank>
    <before_parent>0</before_parent>
    <before_spam>0</before_spam>
    <matching>any</matching>
    <disposition>8,5,9,1,4,7</disposition>
    <cat_id>3</cat_id>
    <conditions>
      <condition>
        <noun>subject</noun>
        <verb>contains</verb>
        <predicate>ProCurve</predicate>
      </condition>
      <condition>
        <noun>subject</noun>
        <verb>contains</verb>
        <predicate>123455</predicate>
      </condition>
    </conditions>
  </rule>
  <rule>
    ...
  </rule>
  ...
</rules>

POST …/api.php/rules/#{section_id}/set_conditions/#{rule_id}

Sets the specified rule with the conditions indicated by the submitted XML data.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<conditions>
  <condition>
    <noun>subject</noun>
    <verb>contains</verb>
    <predicate>ProCurve</predicate>
  </condition>
  <condition>
     <noun>subject</noun>
     <verb>contains</verb>
     <predicate>Proline</predicate>
  </condition>
  <condition>
     ...
  </condition>
</conditions>

Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error.