Last Update: 2019-10-02

Address: Get

Request:

<?xml version="1.0"?>
<addressget key="AddressID">
  <value>42</value>
</addressget>
Description of XML-Tags:
Element Format Description
addressget["key"] varchar(30) Determines by which address-field the data-record will be fetched. If "key" is not specified, default-key is AddressID. The fieldname is case-sensitive, so use e.g. Email instead of email. If a non unique field is given only the first record found will be returned.
addressinsert->value varchar(255) used to search in specified address-field

Response:

<?xml version="1.0"?>
<response>
  <code>2000</code>
  <description><![CDATA[OK]]></description>
  <data>
    <address>
      <addressid></addressid>
      <email></email>
      <anrede></anrede>
      <salutationtext></salutationtext>
      <titel></titel>
      <vorname></vorname>
      <nachname></nachname>
      <firma></firma>
      <funktion></funktion>
      <strasse></strasse>
      <plz></plz>
      <ort></ort>
      <land></land>
      <telefon></telefon>
      <fax></fax>
      <internet></internet>
      <mobiltelefon></mobiltelefon>
      <attribute1/>
      <attribute2/>
      <attribute3/>
      <attribute4/>
      <attribute5/>
      <attribute6/>
      <attribute7/>
      <attribute8/>
      <attribute9/>
      <attribute10/>
      <attribute11/>
      <attribute12/>
      <attribute13/>
      <attribute14/>
      <attribute15/>
      <attribute16/>
      <attribute17/>
      <attribute18/>
      <attribute19/>
      <attribute20/>
      <status/>
      <datesignin/>
      <typesignin/>
      <datesignout/>
      <typesignout/>
      <language></language>
      <bounced></bounced>
      <activityrate/>
      <newsletterformat></newsletterformat>
      <medium>
        <customerid></customerid>
        <status></status>
        <typesignin></typesignin>
        <datesignin>0000-00-00</datesignin>
        <typesignout/>
        <datesignout>0000-00-00</datesignout>
        <topicids/>
      </medium>
    </address>
  </data>
</response>
Response-Codes:
Code Description
4201 Error: No address found

Address: GetAddresses

Request:

<?xml version="1.0" encoding="utf-8"?>
<getaddresses source="list" sourceid="">
  <fields>
    <field>Email</field>
    <field>Company</field>
    ...
  </fields>
</getaddresses>
Description of XML-Tags:
Element Format Description
getaddresses["source"] list|filter|topic Determines the source of the requested addresses. Can be either list (for an address list), filter (for a smart address list) or topic (for all addresses subscribed to a certain topic).
getaddresses["sourceid"] int(10) Specifies the internal id of an existing address-list or topic for fetching the addresses.
getaddresses->field->field varchar(255) Field returned for the addresses fetched.

Response:

<?xml version="1.0"?>
<response>
  <code>2000</code>
  <description><![CDATA[OK]]></description>
  <data>
    <address id="">
      <Email><![CDATA[]]></Email>
      <IsExcluded><![CDATA[]]></IsExcluded>
    </address>
    <address id="">
      <Email><![CDATA[]]></Email>
      <IsExcluded><![CDATA[]]></IsExcluded>
    </address>
  </data>
</response>

Address: Insert/Update

Request:

<?xml version="1.0" encoding="utf-8"?>
<addressinsert key="Email" save-empty-fields="0" overrule-blacklist="0" customerid="">
  <email></email>
  <salutation></salutation>
  <salutationtext></salutationtext>
  <title></title>
  <firstname></firstname>
  <lastname></lastname>
  <street></street>
  <zip></zip>
  <city></city>
  <country></country>
  <phone></phone>
  <fax></fax>
  <mobile></mobile>
  <internet></internet>
  <company></company>
  <function></function>
  <attribute1></attribute1>
  ... 
  <attribute20></attribute20>
  <language></language>
  <newsletterformat></newsletterformat>
  {SubscribeInfos}
  <handleoptin></handleoptin>
  <handleoptout></handleoptout>
  <accountmanagerid></accountmanagerid>
</addressinsert>
{SubscribeInfos}

a) For VX/PRO-Accounts or refering to a single customer of an eCRM-Account

<status optin=""></status>
<datesignin></datesignin>
<typesignin></typesignin>
<datesignout></datesignout>
<typesignout></typesignout>
<topicids merge="1"></topicids>
<lists merge="1">
  <list id="" externalid="" />
  <list id="" externalid="" />
  ...
</lists>

b) For refering to multiple customers of an eCRM-Accounts (needs API username/password of Suite-Manager)

<medium>
  <customerid></customerid>    
  <status optin=""></status>
  <datesignin></datesignin>
  <typesignin></typesignin>
  <datesignout></datesignout>
  <typesignout></typesignout>
  <topicids merge="1"></topicids>
  <lists merge="1">
    <list id="" externalid="" />
    <list id="" externalid="" />
    ...
  </lists>
</medium>
...
<medium>
  ...
</medium>
Description of XML-Tags:
Element Format Description
addressinsert["key"] varchar(30) Optional; Determines by which address-field the data-record will be syncronized. if "key" is not specified, default-key is email. This can be used for example if you have stored your own unique UserID in an attribute-field.
addressinsert["save-empty-fields"] 1|0 Optional; If set to "1" empty values will be written to database. default empty values are ignored.
addressinsert["overrule-blacklist"] 1|0 Optional; If set to "1" the address will be removed from blacklist (if exists).
addressinsert["customerid"] integer Optional; ID of customer where to insert/update the address (needs API username/password of Suite-Manager).
addressinsert->email varchar(255)  
addressinsert->salutation male|female|family  
addressinsert->salutationtext varchar(255)  
addressinsert->title varchar(30)  
addressinsert->firstname varchar(255)  
addressinsert->lastname varchar(255)  
addressinsert->street varchar(255)  
addressinsert->zip varchar(10)  
addressinsert->city varchar(255)  
addressinsert->country varchar(255)  
addressinsert->phone varchar(255)  
addressinsert->fax varchar(255)  
addressinsert->mobile varchar(255)  
addressinsert->internet varchar(255)  
addressinsert->company varchar(255)  
addressinsert->function varchar(255)  
addressinsert->attribute1 to
addressinsert->attribute20
varchar(255) There are 20 custom-fields in the address-database, you can rename and set the type of the attributes through eyepin, still you have to use attribute1-attribute20 when using them (doesn't matter if it's an interface or a signup form issue).
addressinsert->language char(2) 2-letter-code (e.g. "en" or "de")
addressinsert->newsletterformat both|html|text "both" means that the newsletter is sent multipart and the client desides which version to show
addressinsert->status or
addressinsert->medium->status
0|1 0..unsubscribe, 1..subscribe
addressinsert->status["optin"] or
addressinsert->medium->status["optin"]
single|double Optional; Overrule the customers default optin-setting
addressinsert->topicids or
addressinsert->medium->topicids
varchar(255) Comma-separeted IDs of topics available in your eyepin-account
addressinsert->topicids["merge"] or
addressinsert->medium->topicids["merge"]
0|1 If set to "1" given Topic-IDs will be merged with the existing Topic-IDs, otherwise existing Topic-IDs will be replaced.
addressinsert->lists["merge"] or
addressinsert->medium->lists["merge"]
0|1 If set to "1" given subscription in address lists will be merged with the existing subscription in address lists, otherwise existing subscription in address lists will be replaced.
addressinsert->lists->list["id"] or
addressinsert->medium->lists->list["id"]
int(10) Optional; Specifies the internal id of an existing address-list.
addressinsert->lists->list["externalid"] or
addressinsert->medium->lists->list["externalid"]
varchar(255) Optional; Specifies the external id of an existing address-list (If also addressinsert->lists->list["id"] is specified, this externalid will be ignored)
addressinsert->handleoptin 0|1 If set to "1" the confirmation-mail for subscription will be sent. This setting is only applicable if status=1. This feature takes single- or double-optin-setting from eyepin preferences.
addressinsert->handleoptout 0|1 If set to "1" the confirmation-mail for unsubscription will be sent. This setting is only applicable if status=0. This feature takes single- or double-optout-setting from eyepin preferences.
addressinsert->accountmanagerid varchar(255) Value depends on account, most likely email or AddressID
Attention: The field which is set by attribute "key" is mandatory. If "key" is not defined then "Email" is mandatory.
Info: Use <![CDATA[text]]> to send html-code or special characters in a field.

Response:

The internal ID of the address record will be returned within response->data.

Response-Codes:
Code Description
4101 Error: Syncfield not given
4102 Error: Email not valid
4103 Error: Address is blacklisted
4104 Error: Address with given email-address already exists
4105 Error: Address with given mobilenumber already exists
4106 Error: Address is owned by another customer and cannot be changed
4107 Error: Invalid syncfield
4108 Error: Address was added, but no medium was set

Address: Delete

Request:

<?xml version="1.0" encoding="utf-8"?>
<addressdelete key="Email">
  <email></email>
  <blacklist></blacklist>
</addressdelete>
Description of XML-Tags:
Element Format Description
addressdelete["key"] varchar(30) Determines by which field the address-record will be deleted. if "key" is not specified, default-key is email.
addressdelete->email varchar(255) For the case that key is "Email". If key is another field, than the value of that field must be specified.
addressdelete->blacklist 1|0 Optional; If set to "1" than the deleted address will also be blacklisted. Defaults to "1".

Response:

There is no return value in response->data.

Info: If API credentials of Suite Manager is used, the address is deleted from all customers.

Address: GetHistory

Currenty not yet public available!

Request:

<?xml version="1.0"?>
<getaddresshistory>
    <address key="Email"></value>
    <type></type>
    <datefrom></datefrom>
    <datetill></datetill>
</getaddresshistory>
Description of XML-Tags:
Element Format Mandatory Default Description
getaddresshistory->address["key"] varchar no Email Key-field by which the address is fetched
getaddresshistory->address varchar(255) yes Value of key-field
getaddresshistory->type newsletter|event|survey|sweepstake|landingpage yes
getaddresshistory->datefrom no Get history from specified date
getaddresshistory->datetill no Get history till specified date

Response for type="newsletter":

<data>
    <item>
        <datetime></datetime>
        <title></title>
        <status></status>
        <views></views>
        <clicks></clicks>
    </item>
    ...
</data>
Description of XML-Tags:
Element Format Description
item->datetime
item->title varchar Title of newsletter
item->status "0" if sent successful or bounce-code
item->views int
item->clicks int

Response for type="sweepstake":

<data>
    <item id="">
        <datetime>YYYY-mm-dd HH:ii:ss</datetime>
        <title></title>
        <won></won>
        <price id=""></price>
    </item>
    ...
</data>
Description of XML-Tags:
Element Format Description
item["id"] int ID of sweepstake
item->datetime YYYY-mm-dd HH:ii:ss Date/Time of participation
item->title varchar Title of sweepstake
item->won 0|1 "1" if user has won
item->price["id"] int ID of price
item->price varchar Title of price

Addresslist: Create/Update

Request:

<addresslistcreate id="" externalid="" isreadonly="">
  <name></name>
</addresslistcreate>
Description of XML-Tags:
Element Format Description
addresslistcreate["id"] int(10) Optional; Specifies the internal id of an existing address-list for updating. If no id is specified, a new address-list will be created.
addresslistcreate["externalid"] varchar(255) Optional; Specifies the external id of an existing address-list for updating (If also addresslistcreate["id"] is specified, this externalid will be ignored)
addresslistcreate["isreadonly"] 0/1 Optional; Specifies if the list should be readonly (cannot be renamed or deleted by users).
addresslistcreate->name varchar(255) Name of the address-list

Response:

The internal ID of the address-list will be returned within response->data.

Addresslist: Add addresses

Request:

<addresslistadd id="" externalid="">
  <addresses key="Email">
    <address>user1@domain.com</address>
    <address>user2.@domain.com</address>
    ...
  </addresses>
</addresslistadd>
Description of XML-Tags:
Element Format Description
addresslistadd["id"] int(10) Optional; Specifies the internal id of an existing address-list for updating. If no id is specified, a new address-list will be created.
addresslistadd["externalid"] varchar(255) Optional; Specifies the external id of an existing address-list for updating (If also addresslistadd["id"] is specified, this externalid will be ignored)
addresslistadd->addresses["key"] varchar(30) Determines by which field the address is added. if "key" is not specified, default-key is email. This can be used for example if you have stored your own unique UserID in an attribute-field.
addresslistadd->addresses->address varchar(255) The address to be added (For example: If key="Email" this would be an email-address)

Response:

There is no return value in response->data.

Addresslist: Remove addresses

Request:

<addresslistremove id="" externalid="">
  <addresses key="Email">
    <address>user1@domain.com</address>
    <address>user2.@domain.com</address>
    ...
  </addresses>
</addresslistremove>
Description of XML-Tags:
Element Format Description
addresslistremove["id"] int(10) Optional; Specifies the internal id of an existing address-list for removing.
addresslistremove["externalid"] varchar(255) Optional; Specifies the external id of an existing address-list for removing (If also addresslistremove["id"] is specified, this externalid will be ignored)
addresslistremove->addresses["key"] varchar(30) Determines by which field the address is removed. if "key" is not specified, default-key is email. This can be used for example if you have stored your own unique UserID in an attribute-field.
addresslistremove->addresses->address varchar(255) The address to be removed (For example: If key="Email" this would be an email-address)

Response:

There is no return value in response->data.

Addresslist: Remove all addresses

Request:

<addresslistremoveall id="" externalid="" />
Description of XML-Tags:
Element Format Description
addresslistremoveall["id"] int(10) Optional; Specifies the internal id of an existing address-list for updating. If no id is specified, a new address-list will be created.
addresslistremoveall["externalid"] varchar(255) Optional; Specifies the external id of an existing address-list for updating (If also addresslistadd["id"] is specified, this externalid will be ignored)

Response:

There is no return value in response->data.

Addresslist: Delete

Request:

<?xml version="1.0" encoding="UTF-8"?>
<addresslistdelete id="9999999">
  <deleteaddresses blacklist="1">1</deleteaddresses>
  <deletelist>0</deletelist>
</addresslistdelete>
Description of XML-Tags:
Element Format Description
addresslistdelete["id"] int Optional; Specifies the internal id of an existing address-list for deleting.
addresslistdelete["externalid"] varchar(255) Optional; Specifies the external id of an existing address-list for deleting (If also addresslistdelete["id"] is specified, this externalid will be ignored)
addresslistdelete->deleteaddresses["blacklist"] 0/1 Determines if deleted addresses are added to blacklist (Default=1)
addresslistdelete->deleteaddresses 0/1 Determines if the addresses in the list should be deleted (Default=0)
addresslistdelete->deletelist 0/1 Determines if the address list should be deleted (Default=1)

Response:

There is no return value in response->data.

Get blacklist

Request:

<getblacklist key="Email">
  <datefrom>YYYY-mm-dd</datefrom>
  <datetill>YYYY-mm-dd</datetill>
  <page>1</page>
  <pagesize>1000</pagesize>
</getblacklist>
Description of XML-Tags:
Element Format Description
getblacklist["key"] varchar(30) Determines which field of each address-record is returned. The only possible keys are "Email" or "Mobilenumber". If "key" is not specified, default-key is "Email".
getblacklist->datefrom YYYY-mm-dd Beginning of the desired date range
getblacklist->datetill YYYY-mm-dd Optional; End of the desired date range. If not specified, the current date will be set.
getblacklist->page Optional; Request a specific page of the result-set (Default=1)
getblacklist->pagesize Optional; Defines the number of returned records (Default=1000)

Response:

<addresses>
  <address key="user1@eyepin.com">
    <type>Type</type>
    <date>YYYY-mm-dd</date>
  </address>
  ...
</addresses>
Description of XML-Tags:
Element Format Description
addresses List of all addresses which were blacklisted in the specified date range.
addresses->address[key] Email or mobilenumber of the blacklisted address
addresses->address->type Type of blacklisting (e.g. "SignOut", "DeleteByCustomer", ..)
addresses->address->date YYYY-nn-dd Date when address was blacklisted
Für Rückfragen stehen wir Ihnen jederzeit gerne unter support@eyepin.com zur Verfügung.