Mail&Mine Whitelabelling

Mail&Mine White Labelling API v2.3

Mail&Mine – White Labelling API (v2.3)

1

v2.3 (10 Aug 2012) Commercial in Confidence.

Not to be reproduced or provided to a 3rd party without written permission from AndMine Pty Ltd.

Contents

1. API Update History ...................................................................................................................... 2

2. Pricing .......................................................................................................................................... 3

3. Incoming Requests and Responses ............................................................................................. 4

4. Incoming Authentication Fields .................................................................................................. 5

5. Incoming Actions ......................................................................................................................... 6

6. Outgoing Notifications .............................................................................................................. 12

7. Outgoing Authentication Fields ................................................................................................ 13

8. Outgoing Actions ....................................................................................................................... 14

9. Status Codes .............................................................................................................................. 15


2



1. API Update History

Incoming requests changed from “POST” to “GET” since API v2.3:

Update "GET"

Users are unique to each company (defined by a unique “URL identifier”), from API v2.1

onwards. Therefore, when checking for username availability, the company needs to be

specified too:

Update action: "user_check"

Addition url

Addition ERR_08

The Mail&Mine White Labelling API v2.0 has an important addition; outgoing

notifications:

Addition action: "upgrade"

Addition SUCC_08

Furthermore, the following modifications have been added to the incoming requests

section of the API since v1.4:

Addition action: "tier"

Addition SUCC_07

Addition ERR_13


3



2. Pricing

Mail&Mine pricing list can be obtained from the website.

For more details, visit:

http://www.mailandmine.com/pricing/

http://www.mailandmine.com/pricing/


4



3. Incoming Requests and Responses

URL : https://secure.andmine.com/api

Request : All requests must use the GET method to pass values.

Response : JSON encoded return value (object) in the form:

{

status : "<STATUS_CODE>",

msg : "message text"

}

The STATUS_CODE will be one of the success codes (SUCC_XX) or one of

the error codes (ERR_XX) that are provided in Section 9.


5



4. Incoming Authentication Fields

manager

(string)

The client “URL identifier” of the manager account (i.e. the parent client)

api_key

(string)

The Mail&Mine provided API Key of the manager account (i.e. the parent client)

action

(string)

The action required by the request, only allowed actions are:

- "signup"

- "credit"

- "disable"

- "url_check"

- "user_check"

- "tier"

Possible Error Codes

ERR_01 The specified action is something not in the above list.

ERR_02 The manager “URL identifier” and API key don’t match.

ERR_03 Daily query limit exceeded.

ERR_04 Unknown error occurred at the server.

IMPORTANT:

All above fields are compulsory for incoming requests.

All URL identifiers MUST be lowercase and only the alphabet (a-z) is allowed; length

must be a minimum of 5 and a maximum of 12 characters ( ).

All usernames MUST be valid emails; account activation details are sent to that

email address.


6



5. Incoming Actions

Sub-client signup (action: "signup")

manager

Authentication fields (section 4) api_key

action

url

(string)

A unique “URL identifier” for the new sub-client (action:

"url_check" can be used to check for uniqueness of the identifiers)

username

(string)

A unique email address of the new sub-client (action: "user_check" can be used to check for uniqueness of the usernames)

The email address should be valid, as activation details are sent to that email.

account

(string)

The account type required by client, only allowed account types are (Monthly and Pay-As-You-Go):

- "monthly"

- "payg"

credit

(int)

[optional] Only required for PAYG (account: "payg") and MUST be

greater or equal to zero (credit >= 0)

Success Codes

SUCC_01 All provided information was valid and the account has been created. An activation email has already been sent to the provided email (username).

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04

Authentication/Server error (section 4)

ERR_07 New client’s provided “URL identifier” already exists in the EDM.

ERR_08 New client’s provided username already exists in the EDM.

ERR_09 The provided account type was unrecognised.

ERR_10 Account type was PAYG (account: "payg"), but credit amount was invalid.


7



Add credit or switch accounts (action: "credit")

manager


action

url

(string)

The “URL identifier” of the client to add credit to (or make monthly payment).

username

(string)

The username of the user performing this action (administrator rights required).

account

(string)

The account type required by client, only allowed account types are (Monthly and Pay-As-You-Go):

- "monthly"

- "payg"

credit

(int)

[optional] Only required for PAYG (account: "payg") and MUST be greater or equal to zero (credit >= 0)

Success Codes

SUCC_02 Adding credit (without an account switch) was successful.

SUCC_03 Account type switching and any applicable credits also added successfully.

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04


ERR_05 Client username is not an admin account.

ERR_06 Client “URL identifier” was unrecognised.

ERR_09 The provided account type was unrecognised.

ERR_10 Account type was PAYG (account: "payg"), but credit amount was invalid.

ERR_12 Due to some admin restrictions, the account switching failed.


8



Disable an account (action: "disable")

manager


action

url

(string) The “URL identifier” of the client to be disabled.

username

(string)

The username of the user performing this action (administrator rights required).

Success Codes

SUCC_04 Disabling the account was successful.

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04


ERR_05 Client username is not an admin account.

ERR_06 Client “URL identifier” was unrecognised.

ERR_10 The account has already been disabled earlier by someone.

NOTE : Enabling a disabled account can be done by making a new payment OR by emailing the

support team (charges may incur).


9



Check availability of URL identifier (action: "url_check")

manager


action

url

(string) The “URL identifier” to be checked for availability.

Success Codes

SUCC_05 “URL identifier” is available.

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04


ERR_07 The “URL identifier” is unavailable.


10



Check availability of username (action: "user_check")

manager


action

url

(string) The “URL identifier” of the client (company).

username

(string) The “username” to be checked for availability.

Success Codes

SUCC_06 The “username” is available.

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04


ERR_06 The “URL identifier” is unknown.

ERR_08 The “username” is unavailable.

NOTE : Users are unique to a company (company is defined by the “URL identifier”). Therefore a

“URL identifier” needs to be checked before checking for “username”.


11



Check monthly tier (action: "tier")

manager


action

url

(string) The “URL identifier” of the client to be queried.

Success Codes

SUCC_07

Valid monthly tier.

The 'msg' part of the returned JSON object will contain the actual tier. The tier can be one of the following (from lowest tier to highest tier).

- "monthly-1" through to "monthly-7"

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04


ERR_13

The account type of the client is wrong; was looking for “Monthly” tier but records states “PAYG”.

This should not happen; as this means the two systems are in inconsistent states.


12



6. Outgoing Notifications

URL : < URL provided by manager account >

This can be modified on the back end of the Mail&Mine settings for manager

account.

Request : All requests will use the GET method to pass values.

Response : JSON encoded return value (object) in the form:

{

status : "<STATUS_CODE>",

msg : "message text"

}

The STATUS_CODE will be one of the success codes (SUCC_XX) or one of

the error codes (ERR_XX) that are provided in Section 2.


13



7. Outgoing Authentication Fields

manager

(string)

The client “URL identifier” of the manager account (i.e. the parent client)

api_key

(string)

The Mail&Mine provided API Key of the manager account (i.e. the parent client)

action

(string)

The action notified by the request, only allowed actions are:

- "upgrade"

Possible Error Codes

ERR_01 The specified action is something not in the above list.

ERR_02 The manager “URL identifier” and API key don’t match.


ERR_04 Unknown error occurred at the server.


14



8. Outgoing Actions

Monthly Account automatic upgrade (action: "upgrade")

manager


action

url

(string) A unique “URL identifier” for the sub-client.

username

(string) The username of the user performing this action.

from

(string) The previous “monthly tier” (from lowest tier to highest tier).


to

(string) The new “monthly tier” (from lowest tier to highest tier).


Success Codes

SUCC_08

Notification has been successfully received by the client system; regardless of acceptance or rejection according to logical requirements of the client’s system.

Mail&Mine logic has more precedence as the Mail&Mine records have already been updated.

Error Codes

ERR_01

ERR_02

ERR_03

ERR_04


NOTE : If the notification returns with an error code or times out, the Mail&Mine system will

notify the system administrator via email (please make sure the email address linked to

the manager account is valid).


15



9. Status Codes

Success Codes

SUCC_01 Account for "<url_identifier>" successfully created. Activation details will be emailed to "<email>".

SUCC_02 Credit of <credit> successfully added to "<url_identifier>".

SUCC_03 Account "<url_identifier>" has been successfully switched to "<account>"; credits have also been updated accordingly.

SUCC_04 Account "<url_identifier>" successfully disabled.

SUCC_05 The URL identifier "<url_identifier>" is available.

SUCC_06 The username "<username>" is available.

SUCC_07 < The valid monthly account tier >

SUCC_08 Notification successfully received.


16



Error Codes

ERR_01 Unknown action.

ERR_02 Parent authentication failed.


ERR_04 Unknown server error.

ERR_05 Unauthorised access; client user requires administrator rights.

ERR_06 Unknown URL identifier "<url_identifier>".

ERR_07 The URL identifier "<url_identifier>" already exists.

ERR_08 The username "<username>" already exists.

ERR_09 Unknown account type.

ERR_10 Invalid credit amount specified.

ERR_11 Account has already been disabled.

ERR_12 Account type cannot be switched.

ERR_13 Account type mismatch.

Mail&Mine Whitelabelling

Documents

addition action

check addition url addition

andmine pty

incoming requests section

upgrade addition succ

tier addition succ

written permission

incoming actions