API reference: Recipients and groups

 API reference: Recipients and groups documents the function signatures, parameters, return values, and error behavior of the Elaine HTTP API.

Note

Function availability depends on the Elaine release and enabled features. Authenticate HTTP requests with an Elaine-issued Bearer JWT.

Functions

api_getGroupInfo

array|integer api_getGroupInfo( int $user_id = '' , string $group_name = '' , string $sysgroups = false )

Get the identifier and corresponding names for all recipient groups. If $user_id is provided, only recipient groups this user has access rights to are returned. If $group_name is provided, only the data matching the given name are returned. If no parameters are provided, all groups are returned.

Parameters

Return Value

api_getGroupMembers

array|integer api_getGroupMembers( int $ev_id , string $type = 'mail' , mixed $field = 'c_email' , string $startdate = '' , int $page , int $results = 1000 )

Delivers a list of recipient profiles, who participate in the respective group ($type=mail), who have unsubscribed within the validity period ($type=mail-x), who belong to the approval list ($type=mail-test) or who have submitted an unconfirmed opt-in request ($type=opt-in). By default, an array is created, which displays the profile IDs on email addresses, however you can also specify a different (individual) data field for this. As a maximum, 1000 can be returned, however, by means of the parameter page the total stock can be run through ($page=1: start with 1001th element). The $startdate includes the start date of the subscription. The format is 'YYYY-MM-DD HH:MM:SS'.

Parameters

Return Value

api_getGroupSubscribequeue

array|integer api_getGroupSubscribequeue( int $ev_id , string $date = '' )

Returns all data sets of open subscribes for the recipient group $ev_id. The result is limited to a maximum of 1000 data sets. Optionally, you can specify a date or time stamp in $date. The time stamp shows from what date on entries in the subscribe queue should be displayed. The format is 'YYYY-MM-DD HH:MM:SS'.

Parameters

Return Value

api_getGroups

array|integer api_getGroups( int $user_id )

Delivers a list of all recipient groups existing in the tenant. You can call up detailed data of the groups individually with the function api_getDetails().

Parameters

Return Value

api_getSegments

array|integer api_getSegments( int $ev_id , int $user_id )

Parameters

Return Value

api_getSubscribequeueEntry

array|integer api_getSubscribequeueEntry( string $email = null , int $ev_id )

Searches the subscribe queue (list of all unconfirmed opt-in requests) for the specified email address $email and returns the found data set when successful. If the address is not found, the return value is false. Optionally, a recipient group ID $ev_id, to which the data set refers, can be specified. Apart from the profile data entered by the user, the returned data set also includes the field 'sub_id' containing the ID of the subscribe request.

Parameters

Return Value

api_getUser

array|integer api_getUser( int $elaine_id , int $group )

Returns an associative array of the complete data set of the recipient profile with the ID $elaine_id. Or false if the profile has not been found.

Parameters

Return Value

api_getUserGrouplist

array|integer api_getUserGrouplist( int $elaine_id , string $type = 'mail' , boolean|string $sysgroups = false )

Returns an array with all group IDs, the recipient profile $elaine_id has subscribed to. Regular email subscribers are output by default, however, you can choose another type via parameter $type. Possible types are: 'mail', 'mail-x', 'mail-test', 'rss', 'rss-x', 'opt-in', 'sendtofriend'; the suffix -x identifies an unsubscribe and -test a trial membership in the approval list.

Parameters

Return Value

api_getUserHistory

array|integer api_getUserHistory( string $c_email = '' , int $p_id , bool $latest = true )

Returns an array with the event log information (opt-in history) of the recipient profile with the specified email address $c_email or ID $p_id. The parameter $latest shows if only recent changes or the complete list shall be called up (The latter will take longer).
When mail-address $c_email and ID $p_id are given both as parameter please consider the following notice:

Parameters

Return Value

api_getUserId

integer api_getUserId( array $data , array $keys = array() )

Returns the ID of the recipient profile that matches to the given data. If in the array $data the properties 'p_id' or 'hash' are set, these will be used for queries. If they are not set, you will need to specify the keys in the array $keys to read the search criteria from $data.

Parameters

Return Value

api_getUserIdByEmail

integer api_getUserIdByEmail( string $email )

Returns the ID of a recipient profile with the email address $email. If the specified address is not found, the return value is false.

Parameters

Return Value

api_getUserIdByExtID

integer api_getUserIdByExtID( int $ext_id )

Returns the ID of a recipient profile referenced via external ID $ext_id. If the specified external ID has not been linked with a profile, the return value is false.

Parameters

Return Value

api_getUserIdByHash

integer api_getUserIdByHash( string $hash )

Returns the ID of a recipient profile referenced via hash $hash. If the specified hash has not been linked with a profile, the return value is false.

Parameters

Return Value

api_getUserIdByProfilefield

integer api_getUserIdByProfilefield( string $name , string $value )

Returns the ID of a recipient profile via a profile field $name and the desired value $value. It is assumed that only fields with unique values (e.g. customer number, user name, etc.) are used, therefore only the first match is returned. If no profile is found, the return value is 0.

Parameters

Return Value

api_groupSubscribeRequest

boolean api_groupSubscribeRequest( array $data , array $groups , int $nl_id , int $datasource_id , string $source_type = 'api' , int $source_id , $consider_blacklist = true )

Creates an opt-in request for recipient profile data, which has been transferred as associative array. Subsequently, the opt-in confirmation email for the given recipient group is sent out. If no corresponding email could be found, the function returns false. In case of multiple subscribes (parameter $groups is an array of the recipient groups to subscribe), you should additionally specify the opt-in mailing to use, explicitly as parameter $nl_id, otherwise the mailing of the presets group is sent. The confirmation email may contain a special ELAINE tag [grouplist], which inserts the subscribed group names separately.

The $datasource_id displays the ID of the data source to use. If this is not set, the default data source of the tenant will be used.

The parameter $consider_blacklist with true prevents the opt-in request for blacklist-users (default) and with false enables the opt-in request for blacklist-users.

Note: If you have already configured actions (scripts or action emails) in the recipient group settings, these will also be executed by the API function. The manual specification of a newsletter ID is usually not required.

Parameters

Return Value

api_recipientGroupCreate

integer api_recipientGroupCreate( string $group_name , int $parent_folder = 0 , array $group_data = array() )

This function creates a new recipient group with the name $group_name. There is no check whether a group with this name already exists. The recipient group can be created below a specific folder $parent_folder or via default in the parent category. All further data for the group can be specified via the array $group_data. The keys are as follows: 'description', 'from_mail', 'from_name', 'reply_to', 'enclose_test', 'website', 'subscribe_url', 'unsubscribe_url'

Parameters

Return Value

api_subscribequeueDelete

boolean|integer api_subscribequeueDelete( int $p_id , int $ev_id )

Deletes the subscribe attempt of the recipient profile $p_id to the group $ev_id.

Parameters

Return Value

api_userAddOptin

array|integer api_userAddOptin( int $p_id , array $optin_flags = null )

Adds any number of opt-in flags to the recipient profile $p_id. These will be used by the ELAINE Privacy Admission Control® (PAC). Possible values in the array $optin_flags are:

• 'OPTIN_GLOBAL_USER_PROFILING'
• 'OPTIN_TERMINAL_DEVICE_DETECTION'
• 'OPTIN_LINK_PROFILING'
• 'OPTIN_USER_PROFILING'
• 'OPTIN_GLOBAL_RESPONSE_PROFILING'
• 'OPTIN_SOCIAL_ACTIVITY_PROFILING'
• 'OPTIN_ADVANCED_FINGERPRINTING'
• 'OPTIN_GEO_PROFILING'

Parameters

Return Value

api_userAssignExtId

boolean|integer api_userAssignExtId( int $user_id , int $ext_id )

Assigns the specified recipient profile $user_id a unique external ID $ext_id. A potentially existing ID for this profile will be overwritten.

Parameters

Return Value

api_userCreateOrUpdate

integer api_userCreateOrUpdate( array $data , array $keys = array() , int $group )

Creates a new recipient profile or updates an existing profile. The recipient data will be specified analogue to the function api_userNew(). At least one identifying data field ('c_email' or a field contained in the parameter $keys) must exist in $data. If you wish to use the user as email recipient at a later stage, you must specify at least one email address (array key 'c_email'). If you specify more than one data field name as parameter $keys Elaine searches for an existing user data set in their order. If the data set contains group data fields (e_ Prefix), the group for which these data fields apply, must be specified under $group.

Parameters

Return Value

api_userDelete

boolean|integer api_userDelete( int $elaine_id )

Deletes the recipient profile with the ID $elaine_id. All potentially existing group assignments of the profile will also be deleted. In case, the deletion fails, e.g. due to an invalid $elaine_id, the return value is false.

Parameters

Return Value

api_userIsInTrash

boolean|integer api_userIsInTrash( int $elaine_id )

This function checks whether the recipient profile with the ID $elaine_id is in the trash.

Parameters

Return Value

api_userIsLocked

boolean|integer api_userIsLocked( int $elaine_id , mixed $groups = false )

This function checks whether the recipient profile with the ID $elaine_id is on the greylist. If $groups=false only the global greylist will be checked.

Parameters

Return Value

api_userIsOnBlacklist

boolean|integer api_userIsOnBlacklist( int $elaine_id , boolean|integer $custom_ev_id = false )

This function checks whether the recipient profile with the ID $elaine_id is on the blacklist. Alternatively, it is possible to query an ev_id of a custom blacklist instead of the system group Blacklist.

Parameters

Return Value

api_userIsOnBouncelist

boolean|integer api_userIsOnBouncelist( int $elaine_id )

This function checks whether the recipient profile with the ID $elaine_id is on the bounce list.

Parameters

Return Value

api_userLock

boolean|integer api_userLock( int $elaine_id , mixed $groups = false )

Puts the recipient profile with the ID $elaine_id on a temporary send blacklist (greylist). The array $groups can contain several group IDs, on whose lists the recipient is added. If no group is given, the recipient will be added to the global greylist. This function is only available if the feature ENABLE_GREYLIST is activated.

Parameters

Return Value

api_userNew

integer api_userNew( array $data , int $ext_id , int $group )

Creates a new recipient profile. The profile data will be specified as an associative array in the parameter $data. In case, the profile shall be used as email recipient at a later stage, you must enter at least one email address (array key 'c_email'). Optionally, you can enter an external id ('ext_id'), which will permanently be linked to the profile. The return value is the ID of the new profile or a negative error code in case of an error. In case, the data set contains group data fields (e_ Prefix), you must specify the group under $group for which these data fields should apply.

Parameters

Return Value

api_userRemoveOptin

array|integer api_userRemoveOptin( int $p_id , array $optin_flags = array() )

Removes all opt-in flags in the recipient profile $p_id which were given in $optin_flags. Valid opt-in flags are listed under api_userAddOptin().

Parameters

Return Value

api_userSetOptin

array|integer api_userSetOptin( int $p_id , array $optin_flags = null )

Overwrites all opt-in flags of the recipient profile $p_id with the flags from $optin_flags. Valid opt-in flags are listed under api_userAddOptin().

Parameters

Return Value

api_userSubscribeGroup

boolean|integer api_userSubscribeGroup( int $elaine_id , int $group , int $datasource_id , string $source_type = 'api' , int $source_id )

Assigns the recipient profile with the ID $elaine_id to the group $group_id. Via $datasource_id you can optionally enter a data source for the subscription.

Parameters

Return Value

api_userSubscribeRequest

array|integer api_userSubscribeRequest( array $data , array $groups , int $datasource_id , string $source_type = 'api' , int $source_id , $consider_blacklist = true )

Creates an opt-in request of the transferred data to the transferred groups. Returns event information to manually edit the group events. Does not execute events automatically, in contrast to api_groupSubscribeRequest(). The $datasource_id shows the ID of the data source to use. If this is not set, the tenant's default data source will be used.

The parameter $consider_blacklist with true prevents the opt-in request for blacklist-users (default) and with false enables the opt-in request for blacklist-users.

Parameters

Return Value

api_userUnlock

boolean|integer api_userUnlock( int $elaine_id , mixed $groups = false )

A locked recipient profile with the ID $elaine_id can be unlocked in the specified groups. If no group is specified, it will be removed from the global greylist. This function is only available if the feature ENABLE_GREYLIST is activated.

Parameters

Return Value

api_userUnsubscribeGroup

boolean|integer api_userUnsubscribeGroup( int $elaine_id , int $group , int $datasource_id , string $source_type = 'api' , int $source_id )

Deletes a group assignment of the recipient profile with the ID $elaine_id to the group $group_id. Via $datasource_id you can additionally specify a data source for the unsubscribe.

Parameters

Return Value

api_userUpdate

integer api_userUpdate( int $user_id , array $data , int $group )

Updates the recipient profile with the ID $user_id with the data transferred as associative array $data. The function returns 1 if successful, otherwise an error code. In case, the data set contains group data fields (e_ prefix), you must specify the group under $group for which these data fields should apply.

Parameters

Return Value

Related topics

 
• API reference
 
• Call the HTTP API with cURL
 
• Authentication, network security, and VPN