Organization API: Marketing Store API
What a storefront calls to grow the audience: subscribe, confirm a double opt-in, the preference center and signup forms, with the store's publishable key in x-publishable-api-key.
What a storefront calls to grow the audience: subscribe, confirm a double opt-in, the preference center and signup forms, with the store's publishable key in x-publishable-api-key. Paths are under /api/v1/orgs/{org_slug}/store/marketing.
Base URL: https://api.coritan.com/api/v1. Paths below are complete.
To try these requests in the browser, open the interactive Organization API reference.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| POST | /api/v1/orgs/{org_slug}/store/marketing/confirm |
Confirm a double opt-in signup with the token from the email's link |
| GET | /api/v1/orgs/{org_slug}/store/marketing/forms/{public_id} |
The public configuration of one signup form, to draw it in a storefront |
| POST | /api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}/views |
Count one view of the form: call it when the form is shown |
| GET | /api/v1/orgs/{org_slug}/store/marketing/preferences |
Get preferences |
| PUT | /api/v1/orgs/{org_slug}/store/marketing/preferences |
Put preferences |
| POST | /api/v1/orgs/{org_slug}/store/marketing/subscribe |
Sign an address up to the store's marketing email |
| POST | /api/v1/orgs/{org_slug}/store/marketing/unsubscribe |
Unsubscribe |
Confirm a double opt-in signup with the token from the email's link
Section titled Confirm a double opt-in signup with the token from the email's linkPOST /api/v1/orgs/{org_slug}/store/marketing/confirm
Confirm a double opt-in signup with the token from the email's link. The contact joins the list (and gets the
list's welcome email, when it has one); opening the link again changes nothing. 400 invalid_token for a token that
is not valid, expired or another store's; 409 unsubscribed when the address left or was suppressed since.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
token |
string | yes | The token from the confirmation email's link. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
The public configuration of one signup form, to draw it in a storefront
Section titled The public configuration of one signup form, to draw it in a storefrontGET /api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}
The public configuration of one signup form, to draw it in a storefront. 404 for a form that is not this store's or is archived.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
public_id |
path | string | yes |
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Count one view of the form: call it when the form is shown
Section titled Count one view of the form: call it when the form is shownPOST /api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}/views
Count one view of the form: call it when the form is shown. Answers 204.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
public_id |
path | string | yes |
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
204 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Get preferences
Section titled Get preferencesGET /api/v1/orgs/{org_slug}/store/marketing/preferences
What the preference center shows: email_masked, the contact's status and the lists it offers, each with
subscribed. 400 invalid_token for a token that is not valid, expired (90 days) or another store's.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_slug |
path | string | yes | |
t |
query | string | yes | The preference center token. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Put preferences
Section titled Put preferencesPUT /api/v1/orgs/{org_slug}/store/marketing/preferences
Save the contact's choices: they end up on exactly list_ids among the lists the preference center offers (422
invalid for another), or on none and off the store's marketing email with unsubscribe_all. Choosing lists
after unsubscribing is the contact's own consent and subscribes them again, unless the address bounced, was
reported as spam or was turned off by the store (409 marketing_blocked). reason is kept with the
unsubscribe.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
t |
string | yes | The preference center token. |
list_ids |
array of integer | no | The lists to be on. |
unsubscribe_all |
boolean or null | no | Leave every list and stop all marketing email. |
reason |
string or null | no | Why, in the person's words. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Sign an address up to the store's marketing email
Section titled Sign an address up to the store's marketing emailPOST /api/v1/orgs/{org_slug}/store/marketing/subscribe
Sign an address up to the store's marketing email. Always {"ok": true, "confirmation_required"} for a valid
address, so a form never learns whether the store knew it. consent must be true. A list that needs a
confirmation click emails the address a link; an address that unsubscribed, bounced or complained stays out.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes | |
first_name |
string or null | no | |
last_name |
string or null | no | |
fields |
object or null | no | Custom field values by key. |
list_ids |
array of integer or null | no | The lists to join. |
list |
string or null | no | One list, by id or by name. |
tags |
array of string or null | no | |
consent |
any or null | no | Must be the boolean true: the person agreed to receive marketing email. |
consent_text |
string or null | no | The words the person agreed to. |
source |
string or null | no | Where on the storefront, such as footer. |
form_id |
string or null | no | A signup form's public id or id. |
turnstile_token |
string or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
202 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Unsubscribe
Section titled UnsubscribePOST /api/v1/orgs/{org_slug}/store/marketing/unsubscribe
Unsubscribe the contact a marketing email was sent to, from every list, with the token of that email's link. The
address goes on the store's suppression list. Answers {"ok": true} as often as it is posted; 400
invalid_token for a token that is not valid or is another store's.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
t |
string | yes | The token from a marketing email's unsubscribe link. |
reason |
string or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |