3. Subscriber

Content of this chapter

This chapter contains web service methods concerning the recipient management.

3.1. AddSubscriber

Namespace: http://agnitas.org/ws/schemas

Creates a new subscriber without binding to a mailing list.

If double checking is enabled, the web service checks, if there is already an entry with the same value in the key column. Existing entries are updated, when overwriting is enabled.

The profile fields „email“, „mailtype“ and „gender“ are required. More profile fields are possible, but must exist in the database.

Use the database names for profile fields in the webservice call. These names can be found in the EMM user interface.

A numeric datasource ID is assigned to every new recipient to mark the origin of the data. It can be committed as the profile field “datasource_id”. If this profile field is missing the default datasource ID of the web service user is used.

Note: Using another key column than "email" can lead to performance reduction. If you want to use another key column please contact your key account manager.

3.1.1. Request elements

Please note, that the XSD data type "string" has to be specified in the request for the elements <key> and <value> of "MapItem".

3.1.2. Response elements

3.1.3. SOAP Faults

A SOAP fault is returned, when at least one of the required profile fields is missing or the format of the email address is invalid.

3.2. AddSubscribers

Namespace: http://agnitas.com/ws/schemas

Creates a list of subscribers without assigning these to a mailing list.

If the duplicate check is activated, the Web service checks whether there are already entries with the same values in the Key column. Existing entries can be overwritten if necessary.

Note: For each item, that would overwrite more than one recipient, an error message is returned.

The profile fields "email", "mailtype" and "gender" are required. Further profile fields are possible but must exist in the database.

Use the database names for profile fields in the webservice call. These names can be found in the EMM user interface.

Note: Using another key column than "email" can lead to performance reduction. If you want to use another key column please contact your key account manager.

Using this webservice for larger data sets is not recommended. Use import feature of EMM instead.

3.2.1. Request Elemente

Subscriber data

Please note, that profile fields require to use the XSD data type "string" for both "key" and "value" in "MapItem".

3.2.2. Response Elemente

Subscriber data

A subscriber record contains either "subscriberID" or "Error". The order of the subscriber data from request is preserved.

3.2.3. SOAP Faults

A SOAP fault is returned if

• double check is enabled and a value in the key column appears more than once

3.3. AddSubscriberBulk

This webservice is deprecated. Use AddSubscribers instead.

Namespace: http://agnitas.org/ws/schemas

Creates a list of subscribers without assigning these to a mailing list.

If the duplicate check is activated, the Web service checks whether there are already entries with the same values in the Key column. Existing entries can be overwritten if necessary.

Note: For each item, that would overwrite more than one recipient, an error message is returned.

The profile fields "email", "mailtype" and "gender" are required. Further profile fields are possible but must exist in the database.

Use the database names for profile fields in the webservice call. These names can be found in the EMM user interface.

Note: Using another key column than "email" can lead to performance reduction. If you want to use another key column please contact your key account manager.

Using this webservice for larger data sets is not recommended. Use import feature of EMM instead.

3.3.1. Request elements

The elements are structured as items and correspond to the structure of an AddSubscriber call.

Please note, that the XSD data type "string" has to be specified in the request for the elements <key> and <value> of "MapItem".

3.3.2. Response elements

Aufbau von items

Aufbau von item

3.4. FindSubscriber

Namespace: http://agnitas.org/ws/schemas

Finds a customer by the given attribute.

If there is more than one matching customer returns one of them in arbitrary manner.

3.4.1. Request elements

3.4.2. Response elements

3.5. GetSubscriber

Namespace: http://agnitas.org/ws/schemas

Returns a list of key-value pairs. The keys are the names of the profile fields, the values are the corresponding values of the profile. Optionally it is possible to reduce the set of profile fields that are returned by this web service. Existence of profile fields is not checked.

3.5.1. Request elements

If the optional argument profilefields is missing, all profile fields are returned.

Optional element:

3.5.2. Response elements

3.6. GetSubscriberBulk

This webservice is deprecated. Use GetSubscribersByIds instead.

Namespace: http://agnitas.org/ws/schemas

Delivers a list of key value pairs for a list of subscriber IDs. The keys are the names of the profile fields, the values are the corresponding values of the profile fields.

In the case of an invalid customer ID, either a data record with ID 0 can be sent back, or an error element. The sequence of elements is retained, thus allowing the response elements to be assigned to the corresponding request elements.

Existence of profile fields is not checked.

Using this webservice for larger data sets is not recommended. Use export feature of EMM instead.

3.6.1. Request elements

The elements are structured as items and correspond to the structure of a GetSubscriber call.

3.6.2. Response elements

Structure of items

Structure of items

item contains one of the following elements:

3.7. GetSubscribersByIds

Namespace: http://agnitas.com/ws/schemas

Returns a list of key value pairs for a list of subscriber IDs. The keys are the names of the profile fields, the values are the corresponding values of the profile fields.

In the case of an invalid customer ID, either a data record with ID 0 can be sent back, or an error element. The sequence of elements is retained, thus allowing the response elements to be assigned to the corresponding request elements.

Existence of profile fields is not checked.

Using this webservice for larger data sets is not recommended. Use export feature of EMM instead.

3.7.1. Request elements

Optional elements:

3.7.2. Response elements

Structure of subscriber

A subscriber contains only of elements data or error.

Structure of data

3.8. UpdateSubscriber

Namespace: http://agnitas.org/ws/schemas

Either creates or updates a subscriber with the given ID.

Subscriber's attributes that are not present in the request will not be changed. Attributes that do not have correspondent fields in the database are ignored. If an attribute of numeric types holds incorrect value a subscriber updates with 0.

Use the database names for profile fields in the webservice call. These names can be found in the EMM user interface.

3.8.1. Request elements

Please note, that the XSD data type "string" has to be specified in the request for the elements <key> and <value> of "MapItem".

3.8.2. Response elements

3.9. UpdateSubscriberBulk

Namespace: http://agnitas.org/ws/schemas

Creates or updates a list of subscribers.

Subscriber's attributes that are not present in the request will not be changed. Attributes that do not have a suitable field in the database are ignored. If numeric fields contain invalid values, these are filled with 0.

Use the database names for profile fields in the webservice call. These names can be found in the EMM user interface.

Using this webservice for larger data sets is not recommended. Use import feature of EMM instead.

3.9.1. Request elements

The elements are structured as items and correspond to the structure of a AddSubscriber call.

Please note, that the XSD data type "string" has to be specified in the request for the elements <key> and <value> of "MapItem".

3.9.2. Response elements

Structure of items

Structure of item

item contains one of the following items:

3.10. DeleteSubscriber

Namespace: http://agnitas.org/ws/schemas

Deletes subscribers by their ID.

Important note: This webservice is not suitable for unsubscribe a recipient. This webservices entirely remove all subscriber data and bindings. To unsubscribe a recipient use webservice

SetSubscriberBinding, SetSubscriberBindingBulk or SetSubscriberBindingWithAction.

3.10.1. Request elements

3.10.2. Response elements

Note: The response has no elements.

3.11. DeleteSubscriberBulk

Namespace: http://agnitas.org/ws/schemas

Deletes the listed subscriber IDs.

The sequence of elements is retained, thus allowing the response elements to be assigned to the corresponding request elements.

Important note: This webservice is not suitable for unsubscribe a recipient. This webservices entirely remove all subscriber data and bindings. To unsubscribe a recipient use webservice

SetSubscriberBinding, SetSubscriberBindingBulk or SetSubscriberBindingWithAction.

Using this webservice for larger data sets is not recommended. Use import feature of EMM instead.

3.11.1. Request elements

The elements are structured as items and correspond to the structure of a DeleteSubscriber call.

3.11.2. Response elements

Structure of items

Structure of items

item contains one of the following elements:

3.12. ListSubscribers

Namespace: http://agnitas.org/ws/schemas

The web service returns a list of subscriber Ids matching a set of search criteria.

3.12.1. Request elements

Only one element of "criteria" or "eql" can be used. If both elements are given, "eql" is used. A detailed documentation on EQL can be found in the EMM manual.

Das Feld criteria hat dabei folgenden Aufbau:

A search criteria is a key-value pair:

The date format uses Java-format tags:

Optional element:

3.12.2. Response elements

3.12.3. SOAP Faults

A Soap Fault with error message is returned in case of an error.