subscribers.getSubscriber

‹ BACK TO API PAGE


Description

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 the email address, contact ID or the 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 of 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 eMS 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.
NOTE: 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.
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 eMS Enterprise database. 345208
email The subscriber's email address john_smith@example.com
external_id The subscriber's external ID as defined within an external system. 123456
firstname First name John
lastname Last name Smith
date_joined Date when 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 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 fields 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 himk. 619-295-1856
message_detail_id mes_cont_id and sent_time from message_contacts, with "-" in between and sent time formated 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 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 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 records 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>


Back to API Reference Guide