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.
Authentication
Authentication requires your Username and API-Key :
curl -X GET https://discover.crosspromo.club/api/newsletters/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me"
Endpoints
Create a new newsletter
All of your users' interaction with our network can be done through a UI that you control - there is no need for users to be referred to us. But we do require that you create newsletter objects in our database for them.
New newsletters will be able to participate immediately by including their link in posts, but we will review them before sending new subscribers to ensure the integrity of the network. Review typically takes a few hours.
Newsletters have six fields:
- 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).
- external_id: optional, for your use.
To create a new newsletter object:
curl -X POST https://discover.crosspromo.club/api/newsletters/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me" \
-F "title=Newsletter Title" \
-F "tagline=An awesome newsletter that everybody will love reading" \
-F "url=https://awesomenewsletter.blog" \
-F "logo=URL to an image resource" \
-F "topic_list=tech, ai" \
-F "external_id=1754"
If the newsletter is created, then the following response will be given:
{
"message": "Newsletter created and pending review.",
"newsletter":{
"external_id":"your internal id for the newsletter",
"reference":"1AUqWb4",
"cross_promotion_link": "https://discover.crosspromo.club/links/list/1AUqWb4/",
"title":"Newsletter Title",
"tagline":"An awesome newsletter that everybody will love reading.",
"url":"https://awesomenewsletter.blog",
"logo":"URL given to an image resource",
"topics":["tech", "ai"],
"active":false,
"created":"2025-07-14T21:33:22.994548Z"
}
}
Three of these return values should be noted:
- reference: is the public id for the newsletter and will be used for reading, updating
and deleting.
- cross_promotion_link: is the link that newsletters must include in their posts to use
the system.
- active: flags if the newsletter is approved and eligible to receive cross-promotions
from others. The newsletter may use its cross_promotion_link immediately (and should so that it will be
owed new readers).
Delete a newsletter
Newsletter objects that you create are administered by you. As such, you may delete them at will.
Deletion is permanent, unrecoverable, and cascades - data associated with the newsletter will also be deleted.
curl -X DELETE https://discover.crosspromo.club/api/newsletters/{reference}/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me"
Read newsletters
You can read all newsletters that you manage with basic GET requests. Just include a newsletter's reference to be specific.
curl -X GET https://discover.crosspromo.club/api/newsletters/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me"
Read a specific newsletter
curl -X GET https://discover.crosspromo.club/api/newsletters/{reference}/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me"
Update a newsletter
All updates are subject to the same review as new objects. Note the api/newsletter-edits route.
Updating is done via PATCH requests, and all six fields can be edited.
curl -X PATCH https://discover.crosspromo.club/api/newsletter-edits/[reference]/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me" \
-F "title=New Title" \
-F "tagline=I just had to change the tagline" \
-F "url=https://awesomenewsletter.blog" \
-F "logo=URL to an image resource" \
-F "topic_list=tech, ai, online culture" \
-F "external_id=1754"
Read newsletter click data
You'll likely want to show users some analytics on how they're performing.
The currency of crosspromo.club is clicks - i.e. readers of one newsletter clicking through to see that of another. You can read click data using the following:
curl -X GET https://discover.crosspromo.club/api/clicks/{reference}/?days=30/ \
-H "Username: AwesomeYou" \
-H "API-Key: UR70776441awe50me"
The expected response will look like the below, where origin is the newsletter that referred and destination is the newsletter that received. References for origin and destination will only be given if the newsletter is administered by one of your users, otherwise they are set to null to prevent data leakage between platforms:
[
{
"origin_reference":null,
"origin_url":"https://origin_url.com",
"destination_reference":"kDpaqSC",
"destination_url":"https://destination_url.com",
"created":"2025-07-15T09:55:59.633994Z"
}
{
"origin_reference":"JryiRe",
"origin_url":"https://origin_url.com",
"destination_reference":"kDpaqSC",
"destination_url":"https://destination_url.com",
"created":"2025-07-15T09:55:59.633994Z"
}
]