Loading...

Last updated: Apr 25 2018

Area: Episerver Campaign Applies to versions: Not applicable

subscribe

This operation adds a new recipient to a recipient list or updates an existing recipient in Episerver Campaign.

The subscribe operation is available in the mail and the form service. To update recipient data using the mail service, we recommend using the updatefields operation instead.

Note: Stick to formatting rules when transmitting recipient data.

Parameters

NameMandatoryDefault valueDescription

bmRecipientId

yes/no

The ID of the new recipient (usually the email address)

If used in the mail service, this parameter is not mandatory (the email address is sent anyway). If used in the form service, the parameter is mandatory.

bmOptInId

No

The ID of an opt-in process

The opt-in process will be started when the parameter is transmitted. If there is a pending opt-in process the recipient has not finished yet, a new opt-in process is started and no error message is returned.

bmOptinFrequencyLimit

No

-

Use this parameter to set a period (in minutes) that defines how long the last opt-in process of the recipient must date back so that a new opt-in process can be started. If, for example, a new recipient is created and a value of 60 is given, then the last opt-in process must date back at least 60 minutes. Otherwise no new opt-in process is started, and no further confirmation mail (opt-in mail) will be sent to this recipient.

Note: This parameter is only relevant with a double opt-in process.

bmFailOnUnsubscribe

No

false

By default, unsubscribed recipients will be reactivated when subscribed again. If this parameter is set to true, unsubscribed recipients are skipped and a message is returned (unsubscribed).

bmOverwrite

No

false

By default, recipients who already exist are recognized as duplicates, and a duplicate message is returned. When you set the parameter to true, all existing data is overwritten with the new data. No duplicate message is returned.

Warning! See the examples below.

bmOptinSource

No

Optional parameter that defines the opt-in source of the recipient

The parameter can only be set using this operation. It is not possible to set or change the value of this parameter afterwards using the Campaign user interface.

bmSanitize

no

Set the value of this parameter to true to convert potentially dangerous characters in the supplied recipient data into their respective HTML equivalents .

...

No

Any parameter that corresponds to a parameter of the recipient list.

Return values

ValueDescription
ok

Recipient successfully added to the recipient list

ok: updated

Only with bmVerbose=true: Recipient data successfully updated

optin_already_started

Only with double opt-in and a given value for bmOptinFrequencyLimit: Another subscribe operation was triggered for the same recipient, but no opt-in process was triggered, because the new subscription was sent during the pre-defined blocking period.

wrong_tag

Authorization failed.

Error codes:

  • 501=wrong authentication tag
  • 502=wrong request IP
  • 503=wrong request method
  • 504=wrong protocol
  • 505=wrong recipient list
  • 506=wrong action
  • 507=action not found

Note: If a verification of the authentication tag does not solve the problem, contact customer support.

duplicate

Dataset already exists (no overwriting).

unsubscribed

Recipient is unsubscribed.

syntax_error

Syntax error in the parameter, e.g., the email address is invalid.

too_many_bounces

The recipient is or has already been subscribed and has exceeded the bounce limit.

blacklisted

Recipient is blacklisted.

system_error

A general error occurred.

Example 1

.../subscribe?bmRecipientId=foo%40example.com&bmOptInId=2131232 

Adds the recipient with the ID "foo@example.com" to the recipient list and starts opt-in process "2131232" for this recipient.

Note: If the recipient already exists, the return value duplicate is sent. No opt-in process is started.

Example 2

.../subscribe?bmRecipientId=foo%40example.com&bmOverwrite=true&bmOptInId=2131232 

Adds the recipient with the ID "foo@example.com" to the recipient list and starts opt-in process "2131232" for this recipient.

Note: If this recipient is already exists, the existing data is overwritten and updated with the new data. No new opt-in process is started.

Warning! If the recipient is on the unsubscribe list, he will be removed from it and overwritten in the recipient list. No opt-in process is started.

Example 3

.../subscribe?bmRecipientId=foo%40example.com&bmOverwrite=false&bmOptInId=2131232 

Adds the recipient with the ID "foo@example.com" to the recipient list and starts opt-in process "2131232" for this recipient.

Note: If the recipient already exists, the return value duplicate is sent. The existing data is not overwritten. No new opt-in process is started.


Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/