SOAP

Info

Service URL (WSDL):

https://www.enewsletter.pl/api/server.php?wsdl

Requirements

TLS v1.2 is currently required for connections.

To use the web service, you need an SSL connection with a private certificate that we issue and sign using our local CA. This provides authentication, authorization and security for the transmitted data.

To generate a certificate on a Linux/Unix server, follow these steps.

Generating personal keys

1. On the server that will connect to SARE, generate a key and a certificate signing request:

openssl req -new -sha256 -newkey rsa:2048 -nodes -keyout [UID].key -out [UID].pem -subj '/O=<Company name>/OU=WebApi/CN=[UID]'

Warning

Make sure to put your UID in the CN field.

2. Send the [UID].pem file to the SARE IT department. Do not send the private key file ([UID].key).
3. To use the keys with PHP5's built-in SOAP module, combine the private .key file and the certificate from [UID]_signed.pem into one .pem file, using the following structure:

-----BEGIN RSA PRIVATE KEY-----
MIICXgIBAAKBgQDpxZYFwQD5VwfsGyluJy5H0hQ2cfhmiHTqHyzZrKwjG/WGtmMd
o0Uy6eNkMfw+vYoHZzrma3dnTjShHfAz6VH4gZgZDSLG6P3WlLMgKgrcTwveRRgK
vvpoXbLllYbVENITuqO7nYU3dJxrP/ILXF/JyBRBL2wNlWkqvjBukRD4fwIDAQAB
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIICPzCCAaigAwIBAgIBCTANBgkqhkiG9w0BAQUFADAmMQ0wCwYDVQQKEwRTQVJF
MRUwEwYDVQQLEwxTQVJFIFJvb3QgQ0EwHhcNMDkwNDIxMTMxMjEyWhcNMTAwNDIx
MTMxMjEyWjAuMQ0wCwYDVQQKEwRUZXN0MQ8wDQYDVQQLEwZXZWJBcGkxDDAKBgNV
-----END CERTIFICATE-----

Then pass this file to the constructor:

$client = new SoapClient('https://www.enewsletter.pl/api/server.php?wsdl', array('local_cert' => "keycert.pem"));

Arguments

The WSDL file specifies which arguments are required. For example:

<xsd:complexType name="Address">
<xsd:all>
<xsd:element name="email" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="status" type="xsd:integer" minOccurs="0" maxOccurs="1"/>
[...]

This means that an Address object must have the email property set, while status is optional.

Types

Complex types

Name	Type	Description
GroupsArray	array	Groups to which a new address should be added.
Address	array/object	A subscriber.
AddressesArray	array	A list of subscribers.
ImportReturn	array/object	Address import result: uid – UID identified during the operation, from the certificate. bad – number of invalid addresses. blocked – number of addresses blocked in the system by the operator. duplicates – number of duplicates.
SimpleAddress	array/object	A simplified address type used when removing addresses from the database.
SimpleAddressesArray	array	A list of subscribers using the simplified type.
RemoveReturn	array/object	Address removal result: uid – UID identified during the operation, from the certificate. removed – number of removed addresses, whose status was changed. errors – number of errors during the operation. blocked – number of addresses blocked in the system by the operator.
LoginReturn	array/object	Login result: login – login success indicator (1 means successful). uid – UID identified during the operation, from the certificate.
CheckGroupReturn	array/object	Group lookup result: exists – boolean indicating whether the group exists. name – group name. short – abbreviated group name. desc – group description. addressees – number of addresses in the group. The name…short values are set only if the group exists.
GroupInfo	array/object	Properties needed to create a group: id – group ID. name – group name. short – abbreviated group name. desc – group description.
CreateGroupReturn	array/object	Group creation result: status – boolean. info – errors encountered while creating the group, or information about whether the group was created or overwritten.
ListGroupsReturn	array	IDs of groups defined in the system.

Address type

The Address type is used by ImportAddresses to represent addresses being added to or updated in the database.

Name	Type	Required	Default	Description
email	string	YES	n/a	Subscriber's email address.
gsm	string		-	Subscriber's GSM number in international format, e.g. +48123456789.
status	integer		5	Address status: 2 – manually unsubscribed by the operator. 3 – unsubscribed after processing an unsubscribe request; also set when removing addresses through the API. 4 – requested unsubscription by clicking an unsubscribe link in an email. 5 – subscribed, not yet verified, e.g. imported before a verification mailing. 6 – subscribed, unconfirmed, e.g. added through a form and sent a confirmation request. 7 – blocked by the operator. 8 – subscribed and confirmed; mailings can only be sent to addresses with this status.
groups	GroupsArray		-	Groups the address will belong to, for both replacement and update operations. Setting this property resets group membership.
groups_add	GroupsArray		-	Groups to add the address to; this can change group membership during an update.
groups_rem	GroupsArray		-	Groups to remove the address from; this can change group membership during an update.
name	string		-	The name field in the system.
comment	string		-	The comment field in the system.
mail_type	string		text,HTML	Message format the subscriber should receive: text,HTML – HTML newsletter with a TXT part, if one is defined. text – TXT newsletter, or no message if no TXT part is defined.
prop[1-9]	string (max 255)		-	Basic address properties 1–9.
cust_[property name]	string		-	Extended address properties according to the database structure defined in the system.
interface	integer (1–10)		Next import number	Address interface number (source). This determines the subscription notification sent when sendConfirmation is enabled in ImportAddresses.

SimpleAddress type

The SimpleAddress type is used by RemoveAddresses to represent addresses to remove from the database.

Addresses can be identified using:

• An email address, unique within the customer's database.
• An address key, mkey, unique within the customer's database (THIS OPTION IS CURRENTLY INACTIVE).

RemoveAddresses does not physically delete the address from the database. It changes its status to 3 – unsubscribed.

Name	Type	Required	Default	Description
email	string		-	Subscriber's email address.
gsm	string		-	Subscriber's GSM number.

Login method

Call Login once, before any other methods in the synchronization process. It performs the SSL handshake and validates the UID in the certificate's CN field.

ImportAddresses parameters

Name	Type	Required	Default	Description
addresses	AddressesArray	YES	n/a	Address objects to import.
onDuplicate	string		update	Action when an imported address already exists: “update” updates the supplied fields and leaves other data unchanged; “replace” overwrites all data and clears history; “skip” skips the duplicate.
onDuplicateStatusChange	bool		true	Whether to overwrite the status of an existing address. Addresses may become blocked between imports, e.g. after a spam complaint. This flag allows updates without overwriting their status.
sendConfirmation	bool		false	Whether to send a subscription confirmation email. The subscription notification is selected using the imported address's interface, specified by the Address interface property.

RemoveAddresses parameters

Name	Type	Required	Default	Description
addresses	SimpleAddressesArray	YES	n/a	SimpleAddress objects to remove from the database by changing their status.

CheckGroup parameters

Name	Type	Required	Default	Description
groupID	integer	YES	n/a	ID of the group to look up. If it exists, detailed group information is returned.

ClearGroup parameters

Name	Type	Required	Default	Description
groupID	integer	YES	n/a	ID of the group to clear. Addresses are removed from the group and remain in the system. Addresses with no other group membership are moved to the special group 0.

CreateGroup parameters

Name	Type	Required	Default	Description
group	GroupInfo	YES	n/a	Properties of the group to create. If the group already exists, its properties are updated.

RemoveGroup parameters

Name	Type	Required	Default	Description
groupID	integer	YES	n/a	ID of the group to delete. Addresses are removed from the group first and remain in the system.

ListGroups method

Returns an array of IDs of groups defined in the system. This method takes no parameters.

Execute method

This is one of the most important SOAP methods. It lets you execute any SAREscript script and retrieve its output.

Name	Type	Required	Default	Description
command	string	YES	n/a	SAREscript script to execute.
base	string	NO	false	Groups on which to execute the script, e.g. 1,2,3, or “all” for the entire database. The script is then executed in the context of each address. With false, the script does not use addresses and runs only once.
returnResult	bool	NO	false	Applies only when base is not false. With false, returns only the number of processed and skipped addresses, e.g. skipped by system_skipmessage(). With true, also includes the script output.

Attachments

Current WSDL schema for offline analysis.

Sample PHP4 client script using nuSOAP.

Sample PHP5 client script using PHP5:SOAP.

Examples of SOAP methods using PHP5:SOAP.