Mollom API calls

Mollom REST API

REST API call Description
site Site management, including create, update, list, read, and delete; also includes ping for Mollom service
blacklist Blacklist entry management, including create, list, read, and delete
whitelist Whitelist entry management, including create, update, list, read, and delete
content Content management, including create/check and update
tracking Track image request
captcha CAPTCHA management, including create, output, and verify
feedback Send feedback

http://rest.mollom.com/v1/site

Create a site

POST http://rest.mollom.com/v1/site?parameters

Parameter Type Description Accepted values
url String URL of the new site
email String Primary contact email for the site
expectedLanguages String Optional - List of ISO codes of expected languages for content submitted on the site; read more about expected languages
platformName String Optional - Name of the platform running the site (for example, Drupal)
platformVersion String Optional - Version of the platform running the site (for example, 6.20)
clientName String Optional - Name of the Mollom client plugin used (for example, Mollom)
clientVersion String Optional - Version of the Mollom client plugin used (for example, 1.15)

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <site>
    <id>siteId</id>
    <publicKey>publicKey</publicKey>
    <privateKey>privateKey</privateKey>
    <url>example.com</url>
    <email>[email protected]</email>
    <expectedLanguages>
        <languageCode>en</languageCode>
    </expectedLanguages>
    <subscriptionType></subscriptionType>
    <platformName>Drupal</platformName>
    <platformVersion>7.2</platformVersion>
    <clientName>Mollom</clientName>
    <clientVersion>7.x-1.0</clientVersion>
  </site>
</response>

Update a site (also: Verify keys and send client information)

POST http://rest.mollom.com/v1/site/publicKey?parameters

where publicKey is the public API key of the website.

Parameter Type Description Accepted values
platformName String Optional - Name of the platform running the site (for example, "Drupal") - default = keep existing
platformVersion String Optional - Version of the platform running the site (for example, 6.20)
clientName String Optional - Name of the Mollom client plugin used (for example, Mollom)
clientVersion String Optional - Version of the Mollom client plugin used (for example, 1.15)
url String URL of the new site; can be updated only by Mollom resellers
email String Primary contact email for the site; can be updated only by Mollom resellers
expectedLanguages String Optional - List of ISO codes of expected languages for content submitted on the site; read more about expected languages

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <site>
    <id>siteId</id>
    <publicKey>publicKey</publicKey>
    <privateKey>privateKey</privateKey>
    <url>example.com</url>
    <email>[email protected]</email>
    <expectedLanguages>
        <languageCode>en</languageCode>
    </expectedLanguages>
    <subscriptionType></subscriptionType>
    <platformName>Drupal</platformName>
    <platformVersion>7.2</platformVersion>
    <clientName>Mollom</clientName>
    <clientVersion>7.x-1.0</clientVersion>
  </site>
</response>

List sites

Returns a list of all sites that can be accessed with the given authentication.

GET http://rest.mollom.com/v1/site?parameters

Parameter Type Description Accepted values
offset Integer Optional - Number of items to not include in the returned list, counting from 0; default = 0 0 to n
count Integer Optional - Number of items to return; default = all 1 to n

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <list>
    <site>
      <id>siteId</id>
      <publicKey>publicKey</publicKey>
      ...
    </site>
  </list>
  <listCount>20</listCount>
  <listOffset>0</listOffset>
  <listTotal>123</listTotal>
</response>

Read a site

GET http://rest.mollom.com/v1/site/publicKey

where publicKey is the public API key of the website.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <site>
    <id>siteId</id>
    <publicKey>publicKey</publicKey>
    <privateKey>privateKey</privateKey>
    <url>example.com</url>
    <email>[email protected]</email>
    <languages>
      <language>en</language>
    </languages>
    <subscriptionType></subscriptionType>
    <platformName>Drupal</platformName>
    <platformVersion>7.2</platformVersion>
    <clientName>Mollom</clientName>
    <clientVersion>7.x-1.0</clientVersion>
  </site>
</response>

Delete a site

POST http://rest.mollom.com/v1/site/publicKey/delete

where publicKey is the public API key of the website.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
</response>

Error handling

Returned Status Description
HTTP 200 ("OK") with code 200 Site was deleted
HTTP 404 ("Unknown site") with empty response Site does not exist

Ping Mollom with site keys

POST http://rest.mollom.com/v1/site/publicKey/ping

where publicKey is the public API key of the website.

Parameter Type Description Accepted values
url String URL for pong callback; Mollom will call this URL using POST to test round-trip communications

Response format

<response>
  <code>200</ code>
  <message>Response message</message>
</response>

http://rest.mollom.com/v1/blacklist

Create a blacklist entry

POST http://rest.mollom.com/v1/blacklist/publicKey?parameters

where publicKey is the public API key of the website.

Parameter Type Description Accepted values
value String Value to blacklist
reason String Optional - Reason for why the value is blacklisted; default = unwanted spam, profanity, unwanted
context String Optional - Where the entry's value may match; If set to post, either the postTitle or postBody may match; default = allFields allFields, authorName, authorMail, authorIp, authorId, links, postTitle, post
match String Optional - How precise the entry's value may match; default = contains exact, contains
status Integer Optional - Whether or not the entry is enabled; default = 1 0 or 1
note String Optional - Description of the entry; useful in a multi-moderator scenario

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <entry>
    <id>blacklistEntryId</id>
    <created>1305657479</created>
    <status>1</status>
    <lastMatch></lastMatch>
    <matchCount>0</matchCount>
    <value>viagra</value>
    <reason>spam</reason>
    <context>allFields</context>
    <match>contains</match>
    <note></note>
  </entry>
</response>

Delete a blacklist entry

POST http://rest.mollom.com/v1/blacklist/publicKey/blacklistEntryId/delete

where publicKey is the public API key of the website and blacklistEntryId is the ID of an existing blacklist entry.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
</response>
<code></p>

<h4>Error handling</h4>

<p><table>
<tr>
<th>Returned Status</th>
<th>Description</th>
</tr>
<tr>
<td>HTTP 200 (<em>"OK"</em>) with code 200</td>
<td>Entry was deleted</td>
</tr>
<tr>
<td>HTTP 404 (<em>"Unknown blacklist entry"</em>) with empty response</td>
<td>Entry does not exist.</td>
</tr>
</table></p>
</div></div>

<div class="ind">
<h3 id="blacklist-list">List blacklist</h3>

<div class="ind">
<p><strong>GET http://rest.mollom.com/v1/blacklist/<em>publicKey</em></strong></p>

<p>where <strong><em>publicKey</em></strong> is the public API key of the website.</p>

<h4>Request parameters</h4>

<ul>
<li><a href="/mollom/api/rest#response-list">List parameters</a> (optional)</li>
</ul>

<h4>Response format</h4>

<p><code>
<response>
  <code>200</ code>
  <message>Error message</message>
  <list>
    <entry>
      <id>blacklistEntryId</id>
      <created></created>
      ...
    </entry>
  </list>
  <listCount>20</listCount>
  <listOffset>0</listOffset>
  <listTotal>123</listTotal>
</response>

Read a blacklist entry

GET http://rest.mollom.com/v1/blacklist/publicKey/blacklistEntryId

where publicKey is the public API key of the website and blacklistEntryId is the ID of an existing blacklist entry.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <entry>
    <id>1234</id>
    <created>1305657479</created>
    <status>1</status>
    <lastMatch>1305657470</lastMatch>
    <matchCount>123</matchCount>
    <value>viagra</value>
    <reason>spam</reason>
    <context>allFields</context>
    <match>contains</match>
    <note></note>
  </entry>
</response>

http://rest.mollom.com/v1/whitelist

Whitelist entries are checked first. On a positive whitelist match, no other checks are performed; for example:

  • Content API's spam check returns ham.
  • Content API's profanity check returns non-profane.
  • Blacklist entries are not checked.

If no whitelist entry matches, all APIs work as usual.

Create a whitelist entry

POST http://rest.mollom.com/v1/whitelist/publicKey?parameters

where publicKey is the public API key of the website.

Parameter Type Description Accepted values
value String Value to whitelist
context String Where the entry's value may match authorIp, authorId, authorName, authorMail
status Integer Optional - Indicates whether or not the entry is enabled - default = 1 0, 1
note String Optional - Explanation of the entry, which can be useful in a multi-moderator scenario

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <entry>
    <id>whitelistId</id>
  </entry>
</response>

Update a whitelist entry

POST http://rest.mollom.com/v1/whitelist/publicKey/whitelistEntryId?parameters

where publicKey is the public API key of the website and whitelistEntryId is the ID of an existing whitelist entry.

Delete a whitelist entry

POST http://rest.mollom.com/v1/whitelist/publicKey/whitelistEntryId/delete

where publicKey is the public API key of the website and whitelistEntryId is the ID of an existing whitelist entry.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
</response>

Error handling

Parameter Type Description Accepted values
value String Optional - Value to whitelist; default = keep existing
context String Optional - Where the entry's value may match; default = keep existing authorIp, authorId, authorName, authorMail
status Integer Optional - Whether or not the entry is enabled; default = keep existing 0 or 1
note String Optional - Description of the entry; useful in a multi-moderator scenario; default = keep existing
Returned Status Description
HTTP 200 ("OK") with code 200 Entry was deleted
HTTP 404 ("Unknown blacklist entry") with empty response Entry does not exist

List whitelist

GET http://rest.mollom.com/v1/whitelist/publicKey?parameters

where publicKey is the public API key of the website.

Parameter Type Description Accepted values
offset Integer Optional - Number of items to not include in the returned list, counting from 0; default = 0 0 to n
count Integer Optional - Number of items to return; default = all 1 to n

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <list>
    <entry>
      <id>whitelistEntryId</id>
      <created></created>
      ...
    </entry>
  </list>
  <listCount>20</listCount>
  <listOffset>0</listOffset>
  <listTotal>123</listTotal>
</response>

Read a whitelist entry

GET http://rest.mollom.com/v1/whitelist/publicKey/whitelistEntryId

where publicKey is the public API key of the website and whitelistEntryId is the ID of an existing whitelist entry.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <entry>
    <id>whitelistEntryId</id>
    <created></created>
    <status></status>
    <lastMatch></lastMatch>
    <matchCount></matchCount>
    <value></value>
    <context></context>
    <note></note>
  </entry>
</response>

http://rest.mollom.com/v1/content

Create (and check) content

To re-check a post that was checked before, update the content instead of creating a new.

POST http://rest.mollom.com/v1/content?parameters

Parameter Type Description Accepted values
postTitle String Optional - Title of the content
postBody String Optional - Body of the content
authorName String Optional - Name of the content author
authorUrl String Optional - Homepage or website of the content author
authorMail String Optional - Email address of the content author
authorIp String Optional - IP address of the content author
authorId String Optional - Local user ID on the client side of the content author
authorOpenid String Optional - Open IDs (can consist of more than one) of the content author, separated by whitespace
authorCreated String Optional - Unix timestamp for the creation date of the author account
checks String Optional - Checks (can include more than one) to perform (can include more than one); defaults = spam (for new content — without {contentId}) or none (for existing content — with {contentId}) spam, profanity, language
unsure Integer Optional - Whether or nor an unsure response should be allowed for the spam check (which should lead to CAPTCHA); default = 1 1 or 0
strictness String Optional - Strictness of Mollom checks to perform; default = normal strict, normal, relaxed
rateLimit Integer Optional - Time elapsed (in seconds) before the same author can post again; default = 15
honeypot String Optional - Value of a client-side honeypot form element, if populated
stored Integer Optional - Whether or not the content has been stored on the client-side, using 0 during form validation and 1 after successful form submission; When content needs to be processed by the Mollom CMP, this value needs to be set to 1. default = 0 0 or 1
url String Optional - Absolute URL to the stored content
contextUrl String Optional - Absolute URL to parent or context content of the stored content (for example, the URL of the article or forum thread a comment is posted on and not the parent comment that was replied to)
contextTitle String Optional - Title of the parent or context content of the stored content (for example, the title of the article or forum thread a comment is posted on and not the parent comment that was replied to)
contextCreated Integer Optional - Creation date of the parent or context content of the stored content, as a Unix timestamp in seconds (for example, the creation date of the article or forum thread a comment is posted on and not the parent comment that was replied to)
type String Optional - Type of post submitted; type of user indicates user registration form content user
trackingId String Optional - ID generated using the tracking image request and passed with the form; value of -1 should be sent to Mollom if the ID is removed from the form or if its value is emptied

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <content>
    <id>contentId</id>
    <spamClassification>{ham|spam|unsure}</spamClassification>
    <profanityScore>0.0</profanityScore>
    <reason></reason>
    <languages>
      <language>
        <languageCode>en</languageCode>
        <languageScore>1.0</languageScore>
      </language>
      <language>
        <languageCode>de</languageCode>
        <languageScore>0.5</languageScore>
      </language>
    </languages>
    <postTitle></postTitle>
    <postBody></postBody>
    <authorName></authorName>
    <authorUrl></authorUrl>
    <authorMail></authorMail>
    <authorIp></authorIp>
    <authorId></authorId>
    <authorOpenid>
      <id></id>
      <id></id>
    </authorOpenid>
  </content>
</response>

Response parameters

  • contentId:
    If contained in the request and it can be validated in the system, the same is returned. Otherwise, a new unique contentId is returned.
  • *score and *classification: (optional)
    These elements are only returned when requested in checks; e.g.,
    • checks=spam returns spamClassification
    • checks=profanity returns profanityScore
    • etc.
  • *score values are floating point values with a precision of 2, ranging between 0.00 and 1.00.
    • profanityScore = 0.0 means not profane (0% profane).
    • profanityScore = 1.0 means profane (100% profane).
    • etc.
  • reason: (optional)
    A single-word string denoting the reason for the content classification; e.g.:
    • "rateLimit": Author was seen on Mollom-protected sites during the given rateLimit time-frame.
    • ...

Update (and optionally re-check) content

POST http://rest.mollom.com/v1/content/contentId

where contentId is an existing content ID.

Request parameters

The content is only re-checked if the checks parameter is passed. Otherwise, the content properties are updated only.

See Create content.

http://rest.mollom.com/v1/tracking

Tracking Image Request

Generates a Mollom tracking image that can be embedded in a form to enable form behavior analysis. The trackingID generated must be passed as a hidden field along with the form. This trackingID is then submitted to checkContent along with other form content. A new request must be generated for each form load.

GET http://rest.mollom.com/v1/tracking/{trackingId}.png?public_key={publicKey}&timestamp={timestamp}

where trackId is an HMAC-SHA1 hash of the public key concatenated with the current timestamp using the private key as the seed, publicKey is the public API key of the website, and timestamp is the Unix timestamp in seconds used to generate the trackingId.

Response

A one-by-one pixel transparent PNG image to be included in the page. If the tracking ID is invalid, the call returns an HTTP 404 Not Found status code instead.

http://rest.mollom.com/v1/captcha

Create a CAPTCHA resource

POST http://rest.mollom.com/v1/captcha?parameters

Parameter Type Description Accepted values
type String Type of CAPTCHA to create image or audio
ssl Integer Optional - Whether or not to create a CAPTCHA URL using HTTPS; available only for paid subscriptions; default = 0 1 or 0
contentId String ID of a content resource to which to link the CAPTCHA, in case the Content API was unsure

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <captcha>
    <id>captchaId</id>
    <url>http://my.captcha/location.png</url>
  </captcha>
</response>

Retrieve a CAPTCHA resource

Unlike all other API calls, CAPTCHA resources are requested by the client-side browser of an end-user.

GET captchaUrl

where captchaUrl is the URL of a CAPTCHA resource, as returned by Mollom.

CAPTCHA resources have to be explicitly created prior to using them. The resource URL cannot be constructed manually.

Response format

@Produces media

Error handling

Returned Status Description
HTTP 200 OK ("OK") with raw media content CAPTCHA resource exists and can be delivered
HTTP 404 Not Found ("Unknown CAPTCHA resource") with empty response CAPTCHA resource does not exist.
HTTP 409 Conflict ("CAPTCHA was processed already") with empty response CAPTCHA resource exists, but was already processed/updated (solved or not), and can no longer be shown or solved.
HTTP 410 Gone ("Expired CAPTCHA") with empty response CAPTCHA resource previously existed, but has expired and can no longer be shown or solved.

Verify a captcha

POST http://rest.mollom.com/v1/captcha/captchaId?parameters

where captchaId is the ID of the CAPTCHA resource.

Parameter Type Description Accepted values
solution String Answer provided by the author
authorName String Optional - Name of the content author
authorUrl String Optional - Homepage or website URL of the content author
authorMail String Optional - Email address of the content author
authorIp String Optional - IP address of the content author
authorId String Optional - Local user ID of the content author on the client site
authorOpenid String Optional - Open IDs (can consist of more than one) of the content author, separated by whitespace
rateLimit Integer Optional - Time elapsed (in seconds) before the same author can post again; default = 15
honeypot String Optional - Value of a client-side honeypot form element, if populated

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <captcha>
    <id>captchaId</id>
    <solved>1</solved>
    <reason>rateLimit</reason>
    <authorName></authorName>
    <authorUrl></authorUrl>
    <authorMail></authorMail>
    <authorIp></authorIp>
    <authorId></authorId>
    <authorOpenid></authorOpenid>
  </captcha>
</response>
  • solved:
    Whether the provided solution was correct (1) or not (0).
  • reason: (optional)
    A single-word string denoting the reason for why the CAPTCHA solution was deemed to be incorrect:
    • "rateLimit": Author was seen on Mollom-protected sites during the given rateLimit time-frame.
    • "expired": The CAPTCHA resource expired.
    • ...

Error handling

Returned Status Description
HTTP 200 OK with code 200 and (optional) reason CAPTCHA resource exists and was solved (1) or not (0)
HTTP 404 Not Found with empty response CAPTCHA resource does not exist
HTTP 410 Gone with code 410 and reason expired CAPTCHA resource previously existed, but has expired and can no longer be solved.

http://rest.mollom.com/v1/feedback

Send feedback

POST http://rest.mollom.com/v1/feedback?parameters

Parameter Type Description Accepted values
contentId String Optional if captchaId is entered - Existing content ID
captchaId String Optional if contentId is entered - Existing CAPTCHA ID
reason String Reason for why the content associated with either contentId or captchaId is being reported approve, spam, profanity, unwanted, delete
type String Optional - Type of feedback submitted; select flag for end users flagging content to submit feedback or select moderate for administrative moderation; default = moderate flag or moderate
authorIp String Optional - IP address of the content author
authorId String Optional - Local user ID of the content author on the client side
authorIp String Optional - IP address of the content author
authorOpenid String Optional - Open IDs (can consist of more than one) of the content author, separated by whitespace
source String Optional - Single word string identifier for the user interface source; can be tracked along with the feedback to provide a more complete picture of how feedback is used and submitted on the site

Either a contentId or a captchaId is required.

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
</response>

Error handling

Returned Status Description
HTTP 200 OK with code 200 Feedback was stored
HTTP 400 Bad Request ("Missing resource ID") with empty response Neither a contentId nor a captchaId was specified
HTTP 400 Bad Request ("Invalid reason") with empty response reason was specified, but it is not one of the supported strings
HTTP 400 Bad Request ("Invalid type"") with empty response type was specified, but it is not one of the supported strings

Add new comment

About text formats

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
By submitting this form, you accept the Mollom privacy policy.