5. Subscriber Binding
Content of this chapter
This chapter contains web service methods concerning the bindings of a subscriber to a mailinglist.
5.1. SetSubscriberBinding
Namespace: http://agnitas.org/ws/schemas
Binds a subscriber with a mailing list, or updates the binding if it already exists.
5.1.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of a customer to bind |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing list to bind customer to |
| mediatype | {http://www.w3.org/2001/XMLSchema}int | media type Email: 0, SMS:4 |
| status | {http://www.w3.org/2001/XMLSchema}int | status of a subscriber on the mailing list |
| userType | {http://www.w3.org/2001/XMLSchema}string | type of user |
| remark | {http://www.w3.org/2001/XMLSchema}string | comment to binding |
| exitMailingID | {http://www.w3.org/2001/XMLSchema}int | ID of unsubscribe mailing |
5.1.2. Response elements
Note: The response has no elements.
5.1.3. SOAP Faults
A SOAP fault is returned, if any of the following cases occurs:
- mandatory request field is absent
- 'customerID' or 'mailinglistID' is not positive
- 'exitMailingID' is negative
- 'mediatype' or 'userType' is out of designated range
- 'remark' exceeds allowed length
- there is no customer or mailing list that matches with the provided ID
- exitMailingID > 0 but the mailing does not exist
5.2. SetSubscriberBindingWithAction
Namespace: http://agnitas.org/ws/schemas
Enters a new subscriber into a mailing list or updates an already existing entry. The EMM action is subsequently executed.
The action has the limitation that the only action step may be "Send action-based mailing".
5.2.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of a customer to bind |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing list to bind customer to |
| mediatype | {http://www.w3.org/2001/XMLSchema}int | media type Email: 0, SMS:4 |
| status | {http://www.w3.org/2001/XMLSchema}int | status of a subscriber on the mailing list |
| bindingType | {http://www.w3.org/2001/XMLSchema}string | type of user |
| remark | {http://www.w3.org/2001/XMLSchema}string | comment to binding |
| exitMailingID | {http://www.w3.org/2001/XMLSchema}int | ID of unsubscribe mailing |
| actionID | {http://www.w3.org/2001/XMLSchema}int | ID of action to execute |
| runActionAsynchronous | {http://www.w3.org/2001/XMLSchema}boolean | If true, webservice does not wait for action to terminate |
5.2.2. Response elements
| Element | Data type | Description |
|---|---|---|
| value | {http://www.w3.org/2001/XMLSchema}boolean | Result of execution of actions (true: success, fail: error) |
5.2.3. SOAP Faults
A SOAP fault is returned, if any of the following cases occurs:
- mandatory request field is absent
- 'customerID' or 'mailinglistID' is not positive
- 'exitMailingID' is negative
- 'mediatype' or 'userType' is out of designated range
- 'remark' exceeds allowed length
- there is no customer or mailing list that matches with the provided ID
- exitMailingID > 0 but the mailing does not exist
5.3. SetSubscriberBindingBulk
Namespace: http://agnitas.org/ws/schemas
Enters a list of subscribers into a mailing list or updates already existing entries.
Using this webservice for larger data sets is not recommended. Use import feature of EMM instead.
5.3.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| ignoreErrors | {http://www.w3.org/2001/XMLSchema}boolean | If set to false, processing is aborted at first error |
| items | List of {http://agnitas.org/ws/schemas}SetSubscriberBindingRequest | List of bindings to set or update |
The elements are structured as items and correspond to the structure of a SetSubscriberBinding call.
5.3.2. Response elements
| Element | Data type | Description |
|---|---|---|
| items | List of result elements | Contains result for each binding specified in request |
Structure of item
| Element | Data type | Description |
|---|---|---|
| item | Single result element |
Structure of item
item contains one of the following elements:
| Elements | Data type | Description |
|---|---|---|
| SetSubscriberBindingResponse | {http://agnitas.org/ws/schemas}SetSubscriberBindingResponse | Result for a single binding |
| Error | {http://agnitas.org/ws/schemas}Error | Result in case of an error in setting or updating the binding |
5.4. GetSubscriberBinding
Namespace: http://agnitas.org/ws/schemas
Queries for a binding of a particular media type.
Please note: It is recommended to use GetSubscriberBinding only if it is ensured that the binding exists. To check if a subscriber has a specific binding, the list, which is returned by ListSubscriberBinding should be searched for that binding.
5.4.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of a customer |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing list a customer is bound to |
| mediatype | {http://www.w3.org/2001/XMLSchema}int | media type Email: 0, SMS:4 |
| useISODateFormat | {http://www.w3.org/2001/XMLSchema}boolean | Indicator, if ISO8601 date format is used (optional) |
"If useISODateFormat is missing or value is set to false, the date format used so far is enabled, true enables ISO8601 date format."
Optional elements:
| Element | Default behavior, if not specified |
|---|---|
| useISODateFormat | Uses „false“ → simple date format |
5.4.2. Response elements
| Elements | Datentyp | Beschreibung |
|---|---|---|
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | |
| mediatype | {http://www.w3.org/2001/XMLSchema}int | |
| status | {http://www.w3.org/2001/XMLSchema}int | |
| userType | {http://www.w3.org/2001/XMLSchema}string | |
| remark | {http://www.w3.org/2001/XMLSchema}string | |
| exitMailingID | {http://www.w3.org/2001/XMLSchema}int | |
| changeDate | {http://www.w3.org/2001/XMLSchema}dateTime | |
| creationDate | {http://www.w3.org/2001/XMLSchema}dateTime |
5.4.3. SOAP Faults
A SOAP fault is returned, when 'customerID' or 'mailinglistID' is not positive or 'mediatype' is out of designated range or when there is no matching binding.
5.5. ListSubscriberBinding
Namespace: http://agnitas.org/ws/schemas
Queries for all bindings of a particular customer.
5.5.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of a customer |
| useISODateFormat | {http://www.w3.org/2001/XMLSchema}boolean | Indicator, if ISO8601 date format is used (optional) |
"If useISODateFormat is missing or value is set to false, the date format used so far is enabled, true enables ISO8601 date format."
5.5.2. Response elements
| Element | Data type | Description |
|---|---|---|
| item | {http://agnitas.org/ws/schemas}Binding | 0 or more bindings pertaining the customer |
5.5.3. SOAP Faults
A SOAP fault is returned, when there is no subscriber with the given ID.
5.6. ListSubscriberBindingBulk
Namespace: http://agnitas.org/ws/schemas
Requests all registrations for a list of subscribers.
Using this webservice for larger data sets is not recommended. Use export feature of EMM instead.
5.6.1. Request elements
| Element | Data type | Description |
|---|---|---|
| items | List of {http://agnitas.org/ws/schemas}ListSubscriberBindingsRequest | List of customer ID to get |
Optional elements:
| Element | Default behavior, if not specified |
|---|---|
| useISODateFormat | Uses „false“ → simple date format |
The elements are structured as items and correspond to the structure of the ListSubscriberBinding call.
5.6.2. Response elements
| Element | Data type | Description |
|---|---|---|
| items | List of result elements | Contains result for each customer ID specified in request |
Structure of items
| Element | Data type | Description |
|---|---|---|
| item | Single result element |
Structure of items
item contains one of the following elements:
| Elements | Data type | Description |
|---|---|---|
| ListSubscriberBindingResponse | {http://agnitas.org/ws/schemas}ListSubscriberBindingResponse | Binding data for single customer ID |
| Error | {http://agnitas.org/ws/schemas}Error | Result in case of an invalid customer ID |
5.7. DeleteSubscriberBinding
Namespace: http://agnitas.org/ws/schemas
Deletes a binding of a particular media type.
5.7.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of a customer |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing list a customer is bound to |
| mediatype | {http://www.w3.org/2001/XMLSchema}int | media type Email: 0, SMS:4 |
5.7.2. Response elements
Note: The response has no elements.
5.7.3. SOAP Faults
A SOAP fault is returned, when there is no binding to delete.
5.8. DeleteSubscriberBindingBulk
Namespace: http://agnitas.org/ws/schemas
Deletes a list of registrations, according to user and media type.
Using this webservice for larger data sets is not recommended. Use import feature of EMM instead.
5.8.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| ignoreErrors | {http://www.w3.org/2001/XMLSchema}boolean | If set to false, processing is aborted at first error |
| items | List of {http://agnitas.org/ws/schemas}DeleteSubscriberBindingRequest | List of bindings to delete |
The elements are structured as items and correspond to the structure of a DeleteSubscriberBinding call.
5.8.2. Response elements
| Element | Data type | Description |
|---|---|---|
| items | List of result elements | Contains result for each binding specified in request |
Structure of items
| Element | Data type | Description |
|---|---|---|
| item | Single result element |
Structure of item
item contains one of the following elements:
| Elements | Data type | Description |
|---|---|---|
| DeleteSubscriberBindingResponse | {http://agnitas.org/ws/schemas}DeleteSubscriberBindingResponse | Result for a single binding |
| Error | {http://agnitas.org/ws/schemas}Error | Result in case of an error in deleting binding |