subscribers.getSubscriber

4 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

General Information

By default, this method returns an overview of all messages sent to a given subscriber within the past 30 days. You can extend the time horizon to up to the past 90 days.

There are three different ways to identify a subscriber, either by email address, contact ID, or external ID. You must input one and only one of these three identifiers.

This method is best used in conjunction with the Subscribers.getMessageDetail API method to quickly obtain information on emails sent to an individual within the recent past. Use this method to return an overview of messages sent to an individual within a specified time frame. Then, use the subscribers.getMessageDetail API method to retrieve more detailed delivery and response data for a specific message.

If you need information from a broader time range, or from messages sent more than 90 days in the past, use the Statistics.getMessageSubscriberData method to obtain information about promotional messages, and the Transactional.getMessageContactActivity method to obtain information about transactional messages.

Arguments

Field	Description	Field Type	Required	Example
contact_id	The contact ID assigned to the subscriber in the Empower Enterprise database.	number	Conditional Required if <email> and <externa_id> are not provided.	345208
email	The subscriber's email address	string	Conditional Required if <contact_id> and <external_id> are not provided	john_smith@example.com
external_id	The subscriber's external ID as defined within an external system. Your account must be enabled for External ID before you can use this input parameter	string	Conditional Required if <contact_id> and <email> are not provided.	123456
message_history_days_prior	Number of days prior to today's date to retrieve messages sent to the subscriber. The value must be an integer between 1 and 90.	number	No	40

Response

Field	Description	Example
contact_id	The contact ID assigned to the subscriber in the Empower Enterprise database.	345208
email	The subscriber's email address	john_smith@example.com
external_id	The subscriber's external ID is defined within an external system.	123456
firstname	First name	John
lastname	Last name	Smith
date_joined	Date when the subscriber was first added to the database. The date will be in YYYY-MM-DD format.	2006-05-19
email_preference	A one-letter code defining the subscriber's email preference where: P – plain text H – HTML N – No preference	H
address	Street address	123 Main St.
city	City	San Diego
state	State or Province	CA
postal_code	Postal code	92108
country	Country	US
phone_hm	Home phone	619-295-1856
phone_wk	Work phone	619-295-1856
fax	Fax	619-295-1856
timezone	The subscriber's preferred time zone
date_modified	The date that the subscriber's record was last modified. The date will be in YYYY-MM-DD HH:Min:SS format in US Pacific Time Zone.	2008-02-27 13:34:33
is_valid	A boolean value indicating whether or not the subscriber record is valid or not where: 0 – invalid 1 – valid	1
static_segments	This element is the wrapper for all static segments that the subscribe belongs to
segment	This sub-element of the <static_segments> wrapper element acts as the wrapper for each group of static segment data sets returned in the method call.
id	The static segment ID	86
name	The name of the static segment	Text-to-Join Opt-ins
datetime_joined	Date the subscriber was added to the segment in YYYY-MM-DD HH:Min:SS format in US Pacific Time Zone	2006-05-19 10:09:09
custom_fields	This element acts as a wrapper for each custom field containing information about the subscriber.
field	This sub-element of the <custom_fields> wrapper element acts as a wrapper for each group of custom field data sets returned in the method call.
id	The custom field ID number	157
name	The name of the custom field	custom2
value	The custom field value	text-to-join
type	The custom field data type. Options include: date string number zip_code	string
message_history	This element acts as a wrapper for each message data group returned in the method call.
message	This sub-element of the <message_history> wrapper element acts as the wrapper for each group of message data sets returned in the method call.
mes_cont_id	A unique ID that identifies the specific subscriber and the specific message that was sent to him.	619-295-1856
message_detail_id	mes_cont_id and sent_time from message_contacts, with "-" in between and sent time formatted as YYYYMMDD	619-295-1856-20140402
mess_id	The message ID	4300
subject	Subject line	Summer Products have arrived!
message_type	The type of message sent with options being: standard – an email (includes recurring messages too) sent from the Promotional Messaging engine transactional – an email sent from the Transactional Messaging engine	standard
datetime_sent	Date the message was sent in YYYY-MM-DD HH:Min:SS format in the US Pacific time zone	2014-04-02 08:24:32
bounced	An integer indicating the number of times emails sent to the subscriber bounced	0
opens_count	An integer indicating the number of times the message was opened by the subscriber	1
clicks_count	An integer indicating the number of times any links in the message have been clicked	1

Response Codes

Response Code	Response Text	Description
206	30 days of subscriber messages returned	Successful execution of default request, returning 30 days of subscriber message history
207	<number requested> day(s) of subscriber messages returned	Successful execution of default request, returning days of subscriber message history
424	Invalid external ID	The external ID provided in the request does not exist in the subscriber database
428	A required variable is missing from the input	No form of subscriber identifier was submitted.
436	Invalid email address	The value provided for the <email> input parameter does not exist in the subscriber database.
438	The external_id field must be less than 64 characters
439	The external ID should contain alphabetic or numeric characters or both
450	action not taken, too many arguments submitted	Only one form of subscriber identifier can be submitted for this method
451	The provided parameter value is not a number	The value submitted for <message_history_days_prior> is not a number
452	contact_id incorrectly formatted
453	contact_id not found	The contact ID submitted does not exist in the subscriber database
454	Provided parameter value exceeds 90 days or is less than or equal to zero	The input value for <message_history_days_prior> is not an integer between 1 and 90
455	External ID must be used since there are more than one result for the submitted email.	The account is enabled for External ID, and there are more than one contact record having the same email address.
456	External ID feature must be enabled	The <external_id> input parameter is provided, but the account is not enabled for External ID. Contact your account manager to be enabled for this feature.
506	Invalid email format	The value provided for the <email> input parameter is not formatted properly. (e.g. john_smith@example.com)

Example Post

<methodCall>
<methodName>subscribers.getSubscriber</methodName>
<email>john_smith@example.com</email>
</methodCall>

Was this article helpful?

What's Next

Miscellaneous

Table of contents

General Information
Arguments
Response
Response Codes
Example Post