API explained

The premise of the system is you have 40 bytes of custom data to create an association, which you can get back from the replies. Prepended is your API Account ID and the Hash Method which will make 56 byes in total.

In order to do that, the email notification that the receiver is going to reply to, needs that data encoded in the message. It also needs a way of securing that data, verifying it is true, and linking it to your API account.

This is where the API library class will help created appropriate headers using your secret credentials and API Account ID. You will have have provide an end point, or Notification URL for receiving the messages back.

How you use the 40 bytes is up to you. This guide will show an example of how you might use it, where we will divide it into 8 byte chunks. The the api class with auto-prepend them if you give 40 bytes of data.

What sort of data goes into the 56 bytes?

The first two 8 byte sections are reserved for the API Account ID and the Hash Method. You can use hash methods such as md5, sha1, sha256, etc so long as these a supported on that environment. In this case we will use sha1.These two pieces of information are used by the replyPUSH server to verify the message.

The remaining 40 bytes could be anything, but lets use a standard example of a discussion and new comment.

As most likely the email of the receiver will be that of the community account that you will the reply/post under, you don't need to provide this user account, and we suggest you don't. Basically you want to provide just as much as you need.

So the comment has a context which is the discussion, so you need to provide a Record ID, this could be the Comment ID or Discussion ID so long as you are able to get the context from that later. You will most likely want to provide the From User ID of the user who made the comment post the notification is referring to. Lastly if you have multiple types of notification and contexts, of which this is just one you might specify a Type.

We are also going to add a Time Stamp and some Random data to fill the remaining bytes.

The API Account ID and the Mash Method you will pad to the right pad with spaces (8 bytes each). In the custom data, all the numbers we will covert to hex, and left pad with zeros, any text we will right pad with spaces.

Example:

API Account ID: f347ac01

Hash Method: sha1

Record ID: 125

From User ID: 86

Type: newdisc

Timestamp: 1402590148

Random: 1604716014

Results the following:

f347ac01sha1 000000700000056newdisc t5399d3c4ffa605ee

API Account

Broken down:

Reserved Custom
API Account ID Hash Method Record ID From User ID Type Time Stamp Random
f 3 4 7 a c 0 1 s h a 1         0 0 0 0 0 0 7 D 0 0 0 0 0 0 5 6 n e w d i s c   5 3
9
9
d
3
c
4
f
f
a
6
0
5
e
e

Prerequisites

You will need to be able to hook, override, extend, replace or provide the facility, that sends out the email notification.

The bare minimum is to add the Message-ID header and the Reply-To header (see header fields). But you probably want to include some or all of the body of the post it refers to, the title (in the Subject), etc, and information on how to use the service.

The message body itself should begin with <a href="http://replypush.com#rp-message"></a> or ***** yoursite.com message ***** where yoursite.com is your domain. The latter is suitable text only email but we recommend to focus on simple HTML emails as they will give a nicer experience. Although it is not compulsory to include one of these, it is recommended, as it helps mark when the original message begins, and this is used by the service, when processing replies.

The Reply-To header should refer to post@replypush.com as this is the email that receives the replies.

Outward-bound email dissected

Here is an example of a raw email message with headers:

To: Creepers <creepers@gmail.com>
From: Insect Nuts <admin@insectnuts.com>
Reply-To: "Ignorant [at] insectnuts.com" <post@replypush.com>
Subject: [Insect Nuts] Ignorant started a new discussion: How many legs?
Message-ID: <ZjM0N2FjMDFzaGExICAgIDAwMDAwMDdkMDAwMDAwNTZuZXdjb21udDUzOTlkM2M0NWZhNjA1ZWWVdj9ZHE7Ot4jLscKoHrZhBQXrGw==@replypush.com>
Content-Type: text/html; charset = "utf-8"
Content-Transfer-Encoding: quoted-printable

<p>Ignorant started a new discussion, =E2=80=98How many legs?=E2=80=99 in A=
rthropods:</p>
<blockquote>Do centipedes have 100 legs or what?</blockquote>
<p>You can check it out <a href=3D"http://insectnuts.com/forum/discussion/1=
3/how-many-legs">here</a></p>
<p></p>
<p>Have a great day!</p>
<p><br><b>***** reply service *****</b><br></p><p><b>You can reply by the l=
ink provided, or reply directly to this email.</p><p><u>Please put your mes=
sage directly ABOVE the quoted message.</u></p><p>Please ensure privacy of =
others.</p><p>Thank You.</b></p><br>

The message would render something like this:

Ignorant started a new discussion, ‘How many legs?’ in Arthropods:

Do centipedes have 100 legs or what?

You can check it out here

Have a great day!


***** reply service *****

You can reply by the link provided, or reply directly to this email.

Please put your message directly ABOVE the quoted message.

Please ensure privacy of others.

Thank You.


What does that all mean? Well obviously To refers the recipient of the email, the person who receives the notification and is hopefully going to reply. From would be whatever you or you community software would have store as the from name and email. Subject you want it to relate to content. Message-ID is the key part this where the 56 bytes are singed and encoded. Of course the message itself begins with <a href="http://replypush.com#rp-message"></a> and instructions on how to use the service.

In the next section we will look at the signing and encoding of the 56 bytes.