Partners and PMPAPI v1.2

An introduction for the use of PMAPI as a partner (also known as a reseller).

Please note - this guide applies to partner-auth only.

What is the Permission Marketing Partner API?

PMPAPI enables Sign-Up.to partners (also known as resellers) to access a range of API features not available to regular clients via the Permission Marketing API (PMAPI). Additional capabilities available to partners through PMPAPI include:

  • The creation of new Sign-Up.to client accounts.
  • The ability to enable or disable features within client accounts, and to set account restrictions and limits.
  • The ability to transfer email, SMS and Litmus credits between accounts.

PMPAPI can be viewed as a superset of PMAPI.

How does it work?

PMPAPI calls are made in a very similar way to ordinary PMAPI calls. The only difference is the authentication method used. The Partner Hash authentication method is currently supported by PMPAPI, additional authentication types may follow.

When an API call is authenticated using a PMPAPI method, the system grants a higher level of authorisation to the caller. This enables partners to access a wider range of functionality through existing PMAPI endpoints, and to use endpoints which are not available to non-partner clients.

Terminology

For the remainder of this guide, the term "partner-level auth" will be used to describe an API call authenticated with the Partner Hash method (or any other supported partner authentication method). The term "company-level auth" will be used to indicate a call made using regular PMAPI authentication methods, e.g. Token or Hash.

Providing a company ID

When an API call is made with partner-level auth, a company ID may be specified as part of the auth data. Calls made in this way to PMAPI endpoints will be executed as if they were made by the administrative user of the corresponding company.

Some PMPAPI calls do not require a company ID. For example, the POST method on the /account endpoint does not take a company ID; instead it returns the ID of a newly-created company account. If an API call requiring a company ID is made, and no company ID is supplied, the call will fail with a HTTP 401 Unauthorized error. The message Operation requires a company ID will be returned in the X-PMAPI-Error-Message header.

Example: the account endpoint

Like all PMAPI endpoints, the semantics of account are the same regardless of the auth method used. Additional features are available when calls to this endpoint are made with partner-level auth.

To ensure clarity partner-level auth and company-level auth are documented separately. Please note there may be useful information in the company-level documentation that is relevant and useful both types of auth.

The table below demonstrates some of these differences:

Method Company-level auth Partner-level auth
GET
Returns details of the current company: name, address, number of lists and folders, etc. Same response format as with client-level auth, but the "id" field becomes an optional filter field. The endpoint can return details of any or all accounts managed by the partner.
POST
Not available - fails with HTTP 401 Operation requires a higher authentication level.
Creates a new account.
PUT
Not available - fails with HTTP 405 Method Not Allowed.
Not available - fails with HTTP 405 Method Not Allowed.
DELETE
Not available - fails with HTTP 405 Method Not Allowed.
Not available - fails with HTTP 405 Method Not Allowed.

Example: the accountFeatures endpoint

This endpoint is used to enable or disable particular features of an account (e.g. the ability to send SMS messages), and to set various limits enforced on the account. It is read-only when company-level auth is used, and read/write when partner-level auth is used.

The table below demonstrates this:

Method Company-level auth Partner-level auth
GET
Read details of features and limits for the specified company account. Read details of features and limits for the specified company account.
POST
Not available - fails with HTTP 405 Method Not Allowed.
Not available - fails with HTTP 405 Method Not Allowed.
PUT
Not available - fails with HTTP 405 Method Not Allowed.
Adjusts feature and limit settings for the specified company account.
DELETE
Not available - fails with HTTP 405 Method Not Allowed.
Not available - fails with HTTP 405 Method Not Allowed.