REST API v1 (legacy)
Warning
REST API v1 is obsolete. We recommend the new REST API.
The SARE REST API works over HTTP and HTTPS (encrypted connections). Select individual functions by calling the corresponding file.
acq.php
API reference for the script that adds or checks an address in the customer's database.
1. Input parameters (GET or POST)
| Name | Description | Required | Type |
|---|---|---|---|
| s_uid | User's UID in SARE | YES | String |
| s_key | Unique subscription key | YES | String |
| s_email | Email address, up to 255 characters | YES | String |
| s_gsm | Mobile number (SMS module) in +48… format | NO | String |
| s_encoded | Character encoding: ‘utf-8’ (default), ‘iso-8859-2’, ‘iso-8859-1’ | NO | String |
| s_group_[0-31] | Group to join; defaults to 0 (none). Example: s_group_2=1&s_group_4=1 | NO | Bool |
| s_name | Name field | NO | String |
| s_comment | Description field | NO | String |
| s_type | Subscribed newsletter format: ‘text,HTML’ for HTML + TXT (default), ‘text’ for plain text | NO | String |
| s_property[1-9] | Additional property fields | NO | String |
| s_cust_[nazwa] | Extended property fields, according to the structure defined in the system | NO | String/Enum |
| s_interface | Subscription interface number, 1-9; defaults to 0 | NO | Integer |
| s_ip | Subscriber's IP address | NO | String |
| s_no_send | If set, sends no confirmation request and displays no page; returns mainkey only (“key=????????”). Defaults to 0 | NO | Bool |
| s_rv | If set, displays no page and returns the result code only. Defaults to 0 | NO | Bool |
Warning
Encode string parameters, for example with urlencode().
2. Return values and error codes (only when s_rv=1)
| Return value | Description |
|---|---|
| 1 | Address added successfully |
| 4 | Address exists in the database but has not been confirmed |
| 7 | Address exists but is blocked by an operator |
| 8 | Address exists and is already confirmed |
| -1 | Missing required parameter |
| -2 | Invalid email address syntax |
| -3 | Invalid UID syntax |
| -4 | Invalid subscription key |
| -5 | Invalid mobile number syntax |
| -97 | API limit set |
| -98 | Invalid UID |
| -99 | Database connection error |
3. Examples
3.1 Add user@domena.pl to the database for customer UID=001 with global key 16c609d3451133ec09231:
http://s.enewsletter.pl/acq.php?s_uid=001&s_key=16c609d3451155ec09231&s_email=user@domena.pl
Defaults: UTF-8 character encoding and text/HTML message format.
3.2 Add user@domena.pl to customer UID=001 with global key 16c609d3451155ec09231, using text messages and ISO encoding:
3.3 Return the result code only:
http://s.enewsletter.pl/acq.php?s_uid=001&s_key=16c609d3451155ec09231&s_email=user@domena.pl&s_rv=1
4. Testing
Invalid calls display only an error message. Use s_rv=1 to check the error code.
SARE ignores attempts to add the same email address again within 10 minutes. In this case it returns 1 (with s_rv=1 enabled), which may make test results misleading.
upd.php
API reference for the script that updates email addresses in the customer's database.
1. Input parameters (GET or POST)
| Name | Description | Required | Type |
|---|---|---|---|
| s_uid | User's UID in SARE | YES | String |
| s_mkey | Unique key of an address in the customer's database | YES | String |
| s_gsm | Mobile number (SMS module) in +48… format | NO | String |
| s_encoded | Character encoding: ‘utf-8’ (default), ‘iso-8859-2’, ‘iso-8859-1’ | NO | String |
| s_group_[0-31] | Group to join; defaults to 0 (none). Example: s_group_2=1&s_group_4=1 | NO | Bool |
| s_groupoff_[0-31] | Group to leave; defaults to 0 (none). Example: s_groupoff_2=1 | NO | Bool |
| s_name | Name field | NO | String |
| s_comment | Description field | NO | String |
| s_type | Subscribed newsletter format: ‘text,HTML’ for HTML + TXT (default), ‘text’ for plain text | NO | String |
| s_property [1-9] | Additional property fields | NO | String |
| s_cust_[nazwa] | Extended property fields, according to the structure defined in the system | NO | String/Enum |
| s_ip | Updating user's IP address | NO | String |
| s_redirect | URL to redirect to after the update | NO | String |
Warning
Encode string parameters, for example with urlencode().
2. Return values and error codes (only when s_rv=1)
| Return value | Description |
|---|---|
| 1 | Address updated successfully |
| 7 | Address exists but is blocked by an operator |
| -1 | Missing required parameter |
| -2 | Invalid email address syntax |
| -3 | Invalid UID syntax |
| -4 | Invalid address key |
| -5 | Invalid mobile number syntax |
| -97 | API limit set |
| -98 | Invalid UID |
| -99 | Database connection error |
3. Examples
3.1 Set ISO encoding and TXT format for newsletters sent to the address with key 51133ec09231 in customer UID=001's database:
http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231&s_encoded=iso-8859-2&s_type=text
3.2 Change the name of the address with key 51133ec09231 in customer UID=001's database and redirect to www.sare.pl:
3.3 Move the address with key 51133ec09231 in customer UID=001's database from group 1 to group 2:
http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231&s_group_2=1&sgroupoff_1=1
4. Testing
The script changes only the data included in the call parameters. For example:
http://s.enewsletter.pl/upd.php?s_uid=001&s_mkey=51133ec09231
does not change any database data.
Do not pass the email address to modify: it is identified by the s_mkey key.
chk.php
API reference for the script that checks an address in the database.
1. Input parameters (GET or POST)
| Name | Description | Required | Type |
|---|---|---|---|
| s_uid | User's UID in SARE | YES | String |
| s_key | Unique subscription key | YES | String |
| s_email | Email address, up to 255 characters | YES | String |
Warning
Encode string parameters, for example with urlencode().
2. Return values and error codes (only when s_rv=1)
| Return value | Description |
|---|---|
| 8 | Subscribed and confirmed |
| 7 | Blocked address |
| 6 | Subscribed, not confirmed |
| 5 | Subscribed, not verified |
| 4 | Requested unsubscribe |
| 3 | Unsubscribed |
| 2 | Manually unsubscribed |
| 0 | Address not in the database |
| -1 | Missing required parameter |
| -2 | Invalid email address syntax |
| -3 | Invalid UID syntax |
| -4 | Invalid subscription key |
| -97 | API limit set |
| -98 | Invalid UID |
| -99 | Database connection error |
3. Examples
3.1 Check user@domena.pl in the database for customer UID=001 with global key 16c609d3451133ec09231:
http://s.enewsletter.pl/chk.php?s_uid=001&s_key=16c609d3451155ec09231&s_email=user@domena.pl
rm.php
API reference for the script that removes email addresses from the customer's database.
1. Input parameters (GET)
| Name | Description | Required | Type |
|---|---|---|---|
| u | User's UID in SARE | YES | String |
| key | Unique subscription key | YES | String |
| mkey | Unique key of an address in the customer's database | YES | String |
| ml | Mailing code to update | NO | Integer |
2. Examples
2.1 Remove the address with key 9994c from the database for customer UID=001 and master key ba1957be5:
http://s.enewsletter.pl/rm.php?u=001&key=ba1957be5&mkey=9994c
2.2 Remove the address with key 9994c from the database for customer UID=001 and master key ba1957be5, and update mailing 5567cd:
http://s.enewsletter.pl/rm.php?u=001&key=ba1957be5&mkey=9994c&ml=5567cd
3. Testing
The script does not validate the ml argument (mailing code).
Addresses are not physically removed from the database; only their status changes. The same address can therefore be “removed” repeatedly.