Skip to content
Optizmo API

Sync onto a linked list

GET
/api.cgi?action=client_sub_sync
curl --request GET \
  --url 'https://one.optizmo.net/api.cgi?ref=pqmpg&access_link=m-tbjt-j53-b4f8dfbb7f76d3bd0fd92a9f39ba5387&submailer_id=AFF-8821&onid=662b824d577c74b57bf1c4fc647b79c7&advertiser_id=C12412&advertiser_name=BlockBuster&optout_id=O39232&optout_name=Master%20List&campaign_id=K3K3&campaign_name=Spring%20Offer&mailer_id=311111&mailer_name=Acme%20Mailing&mailer_email=ops%40acmemailing.example&check_hash=7583f2e660997b8d1c224a8d74260c51&campaign_set_expiry=2027-01-31&return_format=csv&test_only=success&action=client_sub_sync%3Fref%3Dpqmpg'

For a network that runs another account’s campaign. The upstream account gives the network an access key (m-... or sm-...) for the campaign. This call uses that key to create, in the network’s own account, a linked list that downloads the source’s list, and to register the network’s affiliate on the source campaign, one level down its linked list chain. The affiliate receives an SMAK (sm-..., the key of an affiliate on a linked list) and an Opt-Out link of its own; opt-outs collected through that link are stored in the source’s list.

The advertiser, list, campaign and affiliate parameters behave as in Sync an advertiser, list, campaign and affiliate, with these differences:

  • access_link and submailer_id are required. advertiser_id is also required, and advertiser_name with it; without it: failed,Missing the following input values = advertiser_id.
  • A version 1 list named by optout_id is created as a linked list on the key. An existing standard list cannot be turned into a linked list: failed,Can't change standard Opt-Out List <id> into a linked list.
  • A version 2 optout_id must name an existing linked list created from the same key. Otherwise: failed,Opt-Out List <id> is not a linked list or failed,Linked List <id> has a different access key than <key>.
  • A list already linked from a different key is refused before anything is written: failed,Access Key does not match existing Key in Opt-Out List. A key a move replaced is not this: it is healed automatically, or refused with one of the responses under “When the key you hold was replaced” below, provided the list you name is still the one built from that key’s linked list chain.
  • The key’s list type must match the account: an email key cannot create a list in an SMS-only account (failed,The source list type found in the affiliate access key does not match the current account type associated with the ONID.).
  • Enterprise accounts cannot use this call: failed,Enterprise clients don't have access to this function.
  • Without a campaign_id and mailer_id pair the response is success and the affiliate is not registered on the source campaign.
  • The campaign is resolved before the affiliate (client_sync resolves the affiliate first): a request with a bad campaign_id and a bad mailer_id reports the campaign one.

Values in the check_hash

In this order, skipping any parameter you do not send: action, ref, access_link, submailer_id, onid, advertiser_id, advertiser_name, optout_id, optout_name (version 1 only), campaign_id, campaign_name, mailer_id, mailer_name, mailer_email.

Changing a campaign’s Opt-Out List

Sending an existing campaign_id with a different optout_id moves the campaign exactly as described under Sync an advertiser, list, campaign and affiliate: all checks first, the affiliate’s Opt-Out link for the new source in the response (newly minted, or the one issued earlier if this affiliate has held a link from that source before), previous links unchanged, keys replaced, downstream networks emailed. Two points are specific to this call:

  • The affiliate in the request is registered at the new source under the submailer_id you send. The campaign’s other affiliates are registered there as well; each adopts the submailer_id you send for it on its next sync, so one request per affiliate completes the move without registering any affiliate twice.
  • Moving onto a list linked from a different key replaces the affiliates’ previous SMAKs at the old source; the old source sees the entries marked Access Key Replaced. Moving between two lists linked from the same key leaves every key as it is.

When the key you hold was replaced

A move upstream replaces the access key your linked list was created from, and Optizmo emails the replacement key to the account that holds it. You do not have to wait for it, provided your account owns the linked list built from that key (or from the key that replaced it, or a later replacement of that): the next request that presents the replaced key is healed onto its replacement automatically. The call succeeds and returns the affiliate’s SMAK and Opt-Out link for the current source, exactly as a call presenting the replacement key would, and the response carries that replacement key as access_link. Store it and send it as access_link from then on.

A key a move replaced can also fail to heal:

Response Meaning
failed,The 'access_link' provided was replaced on <date> when campaign '<name>' moved to another opt-out list. Ask the network or advertiser that gave you the campaign for its current access key. Your account owns no linked list built from the key, so nothing is healed. You are told which move replaced the key, and which account made it only when your account created a linked list from the key (the next row). Ask the account that gave you the campaign for its current key.
failed,The 'access_link' provided was replaced on <date> when campaign '<name>' moved to another opt-out list. Ask <mover> for the campaign's current access key. Your account owns the linked list, but there is nothing to heal onto yet: the key was replaced with nothing in its place, the replacements loop back on themselves, there are more of them than one request can follow, or the key that replaced it is itself out of service. <date> and <name> are the replacing move’s own record of itself (a move that recorded no campaign name gives its campaign in place of campaign '<name>'); <mover> is whoever moved the campaign, or, when the move named none, “the network or advertiser that gave you the campaign”, with the sentence ending “…for its current access key.” instead. A campaign that left for another account’s list reads ...was switched off on <date> when campaign '<name>' moved to another account., and a repair of a campaign on the list it is already on reads ...was replaced on <date> by a chain repair of campaign '<name>'.
failed,The 'access_link' provided could not be checked just now. Please retry. The heal could not read what it needed to decide, the key was replaced in the moment between when this request read it and when the heal ran, or the key’s campaign could not be locked against a move. Retry; nothing about your account changes.
failed,The current access key for the 'access_link' provided could not be issued just now. Please retry. The replacement key exists but could not be issued to you this time. Retry.

access_link is present only when the key you sent was replaced; a response on a key still in service has the shape it has always had. A response carrying it is never stored in the cache, so a caller that keeps presenting the replaced key is resolved again on every request.

return_format Where the replacement key appears
csv A fourth field: success,<mailer_url>,<optout_url>,<access_link>, or success,,,<access_link> when the call carried no campaign_id/mailer_id pair to also issue a key for
xml An <access_link> element inside <data>, after <optout_url>
json An access_link value inside data, alongside mailer_url and optout_url

Concurrency

Before anything is created or updated, the call is checked against a concurrent move of the campaign that issued access_link: failed,The campaign that issued the 'access_link' provided is being moved. Please retry. if a move of that campaign is running right now. Retrying resolves the key as it is once the move has committed, healed if you own the linked list it is now part of.

When the call also registers the affiliate on the source campaign (a campaign_id and mailer_id pair), that write is refused rather than made against a campaign mid-move: failed,The campaign is being moved to another Opt-Out List. Please retry. if the move is still running, failed,The campaign could not be checked just now. Please retry. if its lock or its list could not be read, or failed,The campaign moved to another Opt-Out List while this sync ran, so the affiliate was not added to it. Please retry. if it finished in between. An affiliate’s own next sync after another affiliate’s request moved the campaign, which adopts the submailer_id that request sent for it, answers failed,The affiliate's linked list chain for this campaign could not be updated just now. Please retry. if that could not be completed. Retrying any of these picks the campaign up on its current list.

Failures

In addition to the common failures listed under Sync an advertiser, list, campaign and affiliate:

Response Meaning
failed,Invalid 'access_link' type The value is not an m-... or sm-... key.
failed,Failed integrity check on 'access_link' The key does not belong to any campaign.
failed,Campaign is no longer active: Access Revoked The SMAK was switched off by hand in SUPPRESS, so no move replaced it and there is nothing to heal onto.
failed,Campaign is no longer active: Disabled Access A MAK whose affiliate’s access to the source campaign was disabled by hand.
failed,The 'access_link' provided has expired The source has stopped, expired or deleted the campaign, or the key is out of service for another reason that no answer above names. A key a move replaced gets one of the responses under “When the key you hold was replaced” above, also when the key that replaced it is out of service; it gets this plain answer only when its own row is out of service for another reason as well, an expired campaign for example.
failed,Opt-Out List <id> is linked to a source list that no longer exists The linked list’s source can no longer be reached. Recreate the list from a valid key.
failed,Invalid Access Key / failed,Failed Integrity Check The key could not be used to register the affiliate on the source campaign.
failed,The opt-out link for this access key could not be created just now. Please retry. A read that the affiliate’s Opt-Out link needs failed. Nothing was written for the link.
failed,The opt-out link for this access key could not be created, because the linked list chain it belongs to records into no live Opt-Out List. The linked list chain’s source link has no live list left for a new Opt-Out link to record into. Contact support.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
ref
required
string
<= 5 characters

Your tracking platform’s Reference Code (PRC), issued by Optizmo when the integration was set up.

Example
pqmpg
access_link
required
string

A Mailer Access Key (MAK, m-...) or an SMAK (sm-...) issued to this account by another SUPPRESS account for one of its campaigns. The full access URL or the key on its own is accepted; surrounding whitespace is removed.

Example
m-tbjt-j53-b4f8dfbb7f76d3bd0fd92a9f39ba5387
submailer_id
required
string
<= 40 characters

Your platform’s id for the affiliate on the source campaign. Sending the same id for the same key returns the same SMAK.

Example
AFF-8821
onid
required
string

The ONID of the SUPPRESS account the request is for. The account holder finds it on the Account Settings page in SUPPRESS under Affiliate Tracking System, and copies it into your platform.

Example
662b824d577c74b57bf1c4fc647b79c7
advertiser_id
required
string
<= 40 characters

Your platform’s id for the advertiser the linked list belongs to. When sent, advertiser_name is required.

Example
C12412
advertiser_name
string
<= 80 characters

Name of the advertiser. Required when advertiser_id is sent.

Example
BlockBuster
optout_id
string

The Opt-Out List. Unlike the other ids, its length is not checked or truncated.

  • Version 1: your platform’s id for the list. The list is created in the advertiser on first sight and matched on this id afterwards.
  • Version 2: the optoutlist_id of a list the advertiser created in SUPPRESS, as returned by Get Opt-Out Lists. The list must exist.

Required when campaign_id is sent.

Examples

Version 1

O39232
optout_name
string

Name of the Opt-Out List. Version 1 only: required whenever optout_id is sent; the list is renamed when the name changes. Version 2 platforms do not send it; if sent, it is ignored but still part of the check_hash.

Example
Master List
campaign_id
string
<= 40 characters

Your platform’s id for the campaign (offer). The campaign is created on the list named by optout_id on first sight and matched on this id within the advertiser afterwards. Requires optout_id. Sending an existing campaign with a different optout_id moves the campaign to that list; see Changing a campaign’s Opt-Out List.

Example
K3K3
campaign_name
string
<= 150 characters

Name of the campaign. Required when campaign_id is sent; the campaign is renamed when the name changes. Longer values are truncated.

Example
Spring Offer
mailer_id
string
<= 40 characters

Your platform’s id for the affiliate. Affiliates belong to the account, not to an advertiser: the same id names the same affiliate across every advertiser in the account. Created on first sight.

Example
311111
mailer_name
string
<= 80 characters

Company name of the affiliate. Required when mailer_id is sent; updated when it changes. Longer values are truncated.

Example
Acme Mailing
mailer_email
string
<= 500 characters

Contact email of the affiliate. Hashed when sent. Optizmo uses it to tell the affiliate when a campaign’s Opt-Out link or access key changes.

Example
ops@acmemailing.example
check_hash
required
string
/^[0-9a-f]{32}$/

MD5 hex digest of the request’s hashed values, in the order they are listed for this action, followed by your Access Key (PAK). See Authentication for the rules.

Example
7583f2e660997b8d1c224a8d74260c51
advertiser_email
string
<= 80 characters

Contact email stored on the advertiser. Not hashed.

advertiser_phone
string
<= 20 characters

Contact phone number stored on the advertiser. Not hashed.

advertiser_contact
string
<= 70 characters

Contact name stored on the advertiser. Not hashed.

campaign_set_expiry
string format: date

Expiry date of the campaign in YYYY-MM-DD format. Access keys for an expired campaign stop working.

  • Sent with a date: sets the expiry.
  • Sent empty (campaign_set_expiry=): clears the expiry.
  • Omitted: leaves the current expiry as it is.

Not hashed. An unrecognised format is rejected with failed,Campaign Expiry ('campaign_set_expiry') incorrect format (YYYY-MM-DD) - <value>.

Example
2027-01-31
mailer_phone
string
<= 80 characters

Contact phone number of the affiliate. Not hashed.

return_format
string
default: csv
Allowed values: csv xml json

Sets the format of the success or failed answer on the synchronisation and status actions, and of the failure answer on every action. It does not change the success answer of the report and list actions, which is always their own XML document, or of the actions that answer with a page or a redirect. csv, xml and json are the only recognised values; anything else is answered in the csv format, the default. Not included in the check_hash.

test_only
string
Allowed values: success failed

Only honoured by Sync an advertiser, list, campaign and affiliate, Sync onto a linked list, Generate an SMAK, Account report, Get Opt-Out Lists, Advertiser and list settings page and Add opt-outs page; every other action ignores it and runs as normal, so sending it there does not stop the real change. On the actions that honour it, once the request has authenticated, it answers without creating or changing anything, and before the page renders on the two pages actions: failed,Test Failed Output for test_only=failed everywhere it is honoured. For test_only=success: the sync actions return a fixed key pair (https://TESTONLY.optizmo.net/m-test-a00-410324axc3e1eb7a and https://TESTONLY.optoutsystem.net/o-test-a00-546c4dxa10df19b8) in place of real ones, in the same body shape a real success with keys would have; the account report returns that same fixed key pair, not a report document; Get Opt-Out Lists returns a fixed two-entry list document; and the two pages actions return a bare success with no keys, the same shape as a real one with no campaign_id/mailer_id pair. Not included in the check_hash.

Responses

Section titled “ Responses ”

200

Section titled “200”

The request was processed. The body says whether it succeeded; failures are also returned with HTTP 200.

  • success,<mailer_url>,<optout_url>: the affiliate’s access URL and Opt-Out link. The access URL’s last path segment is a MAK (m-...) on a standard list or an SMAK (sm-...) on a linked list.
  • success,<mailer_url>,: an access URL with no Opt-Out link, a deliberate trailing comma rather than a shorter body.
  • success: the records were created or updated, but no campaign_id and mailer_id pair was sent, so no keys were issued.
  • failed,<message>: nothing was changed by the failing step. The messages are listed with each action.

A client_sub_sync call healed onto a replacement key (see Sync onto a linked list) carries a fourth value, access_link, and is never served from the cache; every other response served from the cache carries the header X-Status: cached.

string
Examples

Access key and Opt-Out link issued

success,https://www.affiliateaccesskey.com/m-tbjt-j53-b4f8dfbb7f76d3bd0fd92a9f39ba5387,https://www.optout-tbjt.net/o-tbjt-j53-eeedade91ab3043dea9edcc260d983ef

503

Section titled “503”

The system is in maintenance mode. Retry later. The answer follows return_format: csv (also the answer to a return_format that is neither xml nor json) as text/plain, xml as text/xml, json as application/json.

string
Example
failed,System currently under maintenance