eyepin Documentation

Last Update: 2024-03-21

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). Omit "source" and "sourceid" to get all addresses.
`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></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></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["doi"]` or `addressinsert->medium->status["doi"]`	0\|1	A value of "1" means that a DOI was given in an external system.
`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`.
`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: Unsubscribe

Request:

<?xml version="1.0" encoding="utf-8"?>
<address-unsubscribe key="Email">
  <email></email>
  <type></type>
  <blacklist></blacklist>
</address-unsubscribe>

Description of XML-Tags:

Element	Format	Description
`address-unsubscribe["key"]`	varchar(30)	Determines by which field the address-record will be unsubscribed. if "key" is not specified, default-key is email.
`address-unsubscribe->email`	varchar(255)	For the case that key is "Email". If key is another field, than the value of that field must be specified.
`address-unsubscribe->type`	varchar(255)	Type of unsubscription. Default "API"
`address-unsubscribe->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.

Address: GetHistory

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: List

Request:

<getaddresslists>
  <search></search>
  <order dir="ASC"></order>
</getaddresslists>

Description of XML-Tags:

Element	Format	Description
`getaddresslists->search`	varchar(255)	Optional search keyword
`getaddresslists->order`	Name\|Created\|NumMail	Optional order field (Default "Name")
`getaddresslists->order["dir"]`	ASC\|DESC	Optional order direction (Default "ASC")

Response:

<data>
  <addresslist id="" externalid="">
    <name></name>
    <count></count>
    <activity></activity>
    <created></created>
  </addresslist>
  ...
</data>

Description of XML-Tags:

Element	Format	Description
`addresslist["id"]`	int(10)
`addresslist["externalid"]`	varchar(255)
`addresslist->name`	varchar(255)	Name of list
`addresslist->count`	varchar(255)	Number of contacts
`addresslist->activity`	0-5	Average activity of contacts
`addresslist->created`	YYYY-mm-dd HH:ii:ss	Datetime when list was created

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. Either `addresslistadd["id"]` or `addresslistadd["externalid"]` should be provided.
`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.