📨 Promo API Notifications

Promo API
,
1

Promo Notifications

Promo offers a range of options for developer users’ end user notification needs. Email is currently supported while developers will soon get push notifications (coming), and Slack (coming).

/notifications API route

The Promo API allows for a list or array of Notification payloads as JSON body data in a POST request to https://promo.api.tincre.dev/notifications.

Promo users can simply make a POST request to the /notifications route to send a user email notification.

In order to make requests to this endpoint you’ll need to include auth tokens. Read the docs on how to do that, if you haven’t.

POST request body

Here’s an example POST request body for the /notifications Promo API route:

[
  {
    "pid": "abcdefgh",
    "toEmail": "your-email@your-domain.tld",
    "fromEmail": "support@tincre.dev",
    "subject": "Ad campaign notification",
    "plainTextContent": "Thanks for submitting your payments. Your ads are now in process and will be running shortly.",
    "notificationType": "email"
  }
]

Full example in Python

import requests
import json
from datetime import datetime, timezone
from jose import jwt

rightnow = datetime.utcnow().replace(tzinfo=timezone.utc).timestamp()

token = {
    "sub": "",
    "iss": "http://localhost:8000",
    "cid": "<your client id>",
    "aid": "<your app id>",
    "iat": rightnow,
    "exp": rightnow + 1800,  # 30 minutes
    "scope": "",
    "token_type": "Access",
} # this will be signed with your clientSecret

secret = "<your client secret>" # store in an environment variable!
encoded_token = jwt.encode(token, secret, algorithm="HS256")
 
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {encoded_token}",
}
res = requests.post(
    f"/notifications",
    headers=headers,
    data=json.dumps({
        "pid": "abcdefgh",
        "toEmail": "your-email@your-domain.tld",
        "fromEmail": "support@tincre.dev",
        "subject": "Ad campaign notification",
        "plainTextContent": "Thanks for submitting your payments. Your ads are now in process and will be running shortly.",
        "notificationType": "email"
    }),
)
res.raise_for_status()

Breaking things down

We start by rocking out with some imports:

import requests
import json
from datetime import datetime, timezone
from jose import jwt

Then we setup our Promo API auth token:

rightnow = datetime.utcnow().replace(tzinfo=timezone.utc).timestamp()

token = {
    "sub": "",
    "iss": "http://localhost:8000",
    "cid": "<your client id>", # available in your dashboard
    "aid": "<your app id>", # available in your dashboard
    "iat": rightnow,
    "exp": rightnow + 1800,  # 30 minutes
    "scope": "",
    "token_type": "Access",
} # this will be signed with your clientSecret

We use the token above to encode a signed JSON web token:

secret = "<your client secret>" # store in an environment variable! this comes from your dashboard
encoded_token = jwt.encode(token, secret, algorithm="HS256")

Then we use that signed JWT in our headers for the API:

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {encoded_token}",
}

And lastly, make the request to the /notifications endpoint:

res = requests.post(
    f"/notifications",
    headers=headers,
    data=json.dumps({
        "pid": "abcdefgh",
        "toEmail": "your-email@your-domain.tld",
        "fromEmail": "support@tincre.dev",
        "subject": "Ad campaign notification",
        "plainTextContent": "Thanks for submitting your payments. Your ads are now in process and will be running shortly.",
        "notificationType": "email"
    }),
)
res.raise_for_status()

Summary

In short, the notifications endpoint gives Promo developers an easy way to notify their end users via Promo.

Simply

  1. Create an auth token
  2. Call the /notifications endpoint with an appropriate JSON payload