CrossPromo Club API Docs

Enabling newsletter platforms to offer automated cross-promotion to their users.

To gain access, Contact us.

Overview

Our automated cross-promotion works on a simple principle - if a newsletter sends a subscriber to a partner in our network, then that newsletter should receive a potential new subscriber in return.

The difficulty in ordinary cross-promotion is that two newsletters must have a similar number of subscribers for something close to reciprocal arrangement.

Our way adds an aggregation layer. One newsletter can partner with several others at once, allowing larger newsletters to distribute their subscribers to many partners, and smaller newsletters to pool their referrals. This is done automatically when a newsletter includes its unique link in a post.

Single Sign On

At present, our API is used to facilitate SSO from within your platform to ours. You are the identity provider for your users, and we create accounts from them to use on our platform. Your users are tagged as belonging to you.

Authentication

Authentication requires your API-Key :

            
  curl -X GET https://crosspromo.club/api/new-user/ \
    -H "API-Key: UR70776441awe50me"

Endpoints

Create a new user

Your users are yours, but we need to create accounts for them on our platform so that we can properly monitor sessions and credit their activity to them.

Accounts can technically be created with no information, but the following is strongly advised:

  • email: the user's email address (if your privacy policy and an agreement with us allows you to share it)
  • newsletters: a list of the newsletters that the user manages on your system

Newsletter must/should contain the following information:

  • title: 75 characters or fewer
  • tagline: 255 characters or fewer
  • url: must be unique
  • logo: a URL to an image resource
  • topic_list: optional but highly recommended. Must be given as a single comma-separated string (values are arbitrary)
  • language_list: optional, and will only persist certain languages (others will fail silently)
  • external_id: optional, for your use.

To create a new user:

              
  curl -X POST https://crosspromo.club/api/new-user/
    -H "Content-Type: application/json" \
    -H "API-Key: UR70776441awe50me" \
    -d '{
      "email": "name@somedomain.com",
      "newsletters": [
        {
          "title": "A brand new newsletter",
          "tagline": "All about being a brand new newsletter",
          "url": "https://newnewsletter.com",
          "logo": "URL to an image resource",
          "topic_list": "tech, ai",
          "language_list": "English"
        },
        {
          "title": "Another fantastic newsletter",
          "tagline": "I just love newsletter so much",
          "url": "https://anothernewsletter.com",
          "logo": "URL to an image resource",
          "topic_list": "society, ai",
          "language_list": "English, Spanish"
        }
      ]
    }'

If the user is successfully created, then the following response will be given:

              
  {
    "message":"user created",
    "api_id":"5effc684-4883-4054-a100-d38c920a6ccc",
    "login_url":"https://crosspromo.club/sso-login/27394eee-927a-48c6-86c8-67ef6a57033f/",
    "newsletters":[
      {
        "title": "A brand new newsletter",
        "url": "https://newnewsletter.com"
      },
      {
        "title": "Another fantastic newsletter",
        "url": "https://anothernewsletter.com"
      }
    ]
  }

These return values should be noted:

  • api_id: is the shared id between you and us for that user, you will need it to log the user in via SSO in future interactions.
  • login_url: is a link to an SSO session that will automatically log the user into our platform.
Our suggest new user creation flow is as follows:
  • Send a POST request to https://crosspromo.club/api/new-user/ when your user indicates that they wish to join our platform. Having the user click a button like "Join crosspromo.club" should work well.
  • Store the api_id for that user in your database for future reference.
  • Redirect the user to the login_url in a new window (the SSO session will expire if not used within five minutes).

Log in via SSO

Once users are created, logging them in via SSO is an almost identical process to creating them. This is the required POST request:

              
curl -X POST https://crosspromo.club/api/sso-session-create/ \
  -H "Content-Type: application/json" \
  -H "API-Key: UR70776441awe50me" \
  -d '{
    "api_id": "5effc684-4883-4054-a100-d38c920a6ccc"
  }'

The following response will be given with a login_url

              
{
  "message":"login session created",
  "login_url":"https://crosspromo.club/sso-login/86e93baf-c95c-4e47-bc66-9b0d0be96615/"
}

Redirect the user to the login_url, and they'll be logged into our platform.