Create a Subscription by POST Request

📘

Effort ID Required

To generate an effort_id you must Create a Campaign then Generate a Campaign Link.

[View] the Campaign -> 'Campaign Efforts' table for existing Effort IDs.

The generated link also has the effort_id number in the last part of the URL, e.g., https://{APP_DOMAIN}/o/op/[effort_id]

Usage

To create subscriptions without requiring login access to the OptiPub installation, external partners can POST a request to https://{APP_DOMAIN}/api/o/subscribe.

There are 3 required parameters for the request: email, publication_id, effort_id.

There is also an optional array parameter for segment_ids.

Any other parameters provided are optional and will be treated as subscriber variables. Only variables that are defined in your installation may be used.

Review the curl request code examples in Step 2. below.

SMS Addon

📘

Important SMS Addon Details

The SMS Addon will opt-in the subscription to SMS Messages.

Updating a subscription's SMS Addon with a new or different phone number will automatically send an opt-in SMS message to the phone number.

Sending SMS messages through OptiPub uses the Twilio Integration Messaging Service configured in your OptiPub installation.

The POST request can associate the phone variable to a subscription as an SMS Addon phone number.

The variable name phone must first be created in Variables with the variable type Text.

The parameter "enable_addon": "SMS" is also required in the request body to attach the phone number to the SMS Addon.

A value must be provided to the phone variable when using the enable_addon=SMS parameter.

Review the SMS code example of the curl request in Step 2. below.

Adding an SMS Addon phone number to an existing subscription

To prevent triggering a duplicate subscription event when adding an SMS Addon phone number to an existing subscription, add the parameter "existing_subscription": true (no quotes around 'true').

Review the Existing Sub code example of the curl request in Step 2. below.

Step 1. Collect and provide subscription details to the partner.

Collect the necessary data:

1. Retrieve the publication_id from OptiPub > Administration > Publications.
2. Retrieve the effort_id from OptiPub > Marketing > Campaigns.
3. (Optional) Retrieve segment_ids from OptiPub > Messaging > Segments.
4. (Optional) Retrieve variable names from OptiPub > Messaging > Variables.

Provide this data to the partner:

1. The publication_id, effort_id, and optionally any segment_ids and variable names necessary.
2. The {APP_DOMAIN} of your OptiPub installation. This is the URL you use to log into OptiPub.
   Example: [client].app.optipub.com

3. The link to this document - https://docs.optipub.com/docs/create-a-subscription-by-post-request#step-2-the-partner-will-post-requests-in-json-format

Step 2. The partner will POST requests in JSON format.

Use the code examples below to create a subscription using a POST request.

Partners should be provided with values for the necessary parameters outlined in Step 1.

Partners must only use their own values after email, and any variable name parameters.

Code Examples

Replace {APP_DOMAIN} with an OptiPub domain URL, e.g., [client].app.optipub.com

curl -X POST https://{APP_DOMAIN}/api/o/subscribe \
-H "Content-Type: application/json" \
-d '{
    "email": "[email protected]",
    "publication_id": 123,
    "effort_id": 456789
}'

curl -X POST https://{APP_DOMAIN}/api/o/subscribe \
-H "Content-Type: application/json" \
-d '{
    "email": "[email protected]",
    "publication_id": 123,
    "effort_id": 456789,
    "segment_ids": [1234,5678],
}'

curl -X POST https://{APP_DOMAIN}/api/o/subscribe \
-H "Content-Type: application/json" \
-d '{
    "email": "[email protected]",
    "publication_id": 123,
    "effort_id": 456789",
    "firstname": "Foo",
    "lastname": "Bar"
}'

curl -X POST https://{APP_DOMAIN}/api/o/subscribe \
-H "Content-Type: application/json" \
-d '{
    "email": "[email protected]",
    "publication_id": 123,
    "effort_id": 456789,
    "enable_addon": "SMS",
    "phone": "+15555555555"
}'

curl -X POST https://{APP_DOMAIN}/api/o/subscribe \
-H "Content-Type: application/json" \
-d '{
    "email": "[email protected]",
    "publication_id": 123,
    "effort_id": 456789,
    "enable_addon": "SMS",
    "phone": "+15555555555",
    "existing_subscription": true
}'

curl -X POST https://{APP_DOMAIN}/api/o/subscribe \
-H "Content-Type: application/json" \
-d '{
    "email": "[email protected]",
    "publication_id": 123,
    "effort_id": 456789,
    "segment_ids": [1234,5678],
    "firstname": "Foo",
    "lastname": "Bar",
    "enable_addon": "SMS",
    "phone": "+15555555555"
}'

curl -X POST https://{APP_DOMAIN}/api/o/subscribe ^
-H "Content-Type: application/json" ^
-d "{
    `"email`": `"[email protected]`",
    `"publication_id`": 123,
    `"effort_id`": 456789,
    `"segment_ids`": [123]
}"

segment_ids is an array parameter.

JSON represents arrays with values encased in brackets, e.g., "segment_ids": [123]

Error Watch:

If requests are failing that have segment_ids, check that your process is specifying application/json as the Content-Type. Failure response codes below.

Other Content-Types represent arrays with empty brackets in the parameter, e.g., segment_ids[]:

segment_ids[]=123
segment_ids[]=456

Response Codes

Add the -v flag to the curl command to get a verbose response including the HTTP status code.
Example: curl -v -X POST https://{APP_DOMAIN}/api/o/subscribe \

Success:

HTTP/1.1 201 Created - {"error":false,"data":{...},"message":"Created subscription."}

Failure:

HTTP/1.1 302 Found - Redirect

HTTP/1.1 404 Not Found
HTTP/1.1 500 Server Error