Jump to content

API Parameters

Below is a detailed description of the parameters used by the eConnect Email API:


ApiKey - a unique identification key that informs the API who you are. You can aquire an ApiKey by contacting us and requesting one.  Once acquired, you can get the API key within eConnect Email by clicking the My Account link in the upper-right corner; the API key will be listed next to "SOAP Token." 


ListID - a unique number that identifies each contact list in eConnect Email. You can get a contact list's ID one of two main ways:

  • via the API:  invoke the GetLists method, which will return all lists along with their IDs
  • via the eConnect Email application:  login to eConnect Email, and then click the Contact List menu, and View Contact Lists.  On the resulting page, find the contact list you like, then either hover over its View link -- the "Lists[]" value in the querystring of the link URL is the ID you need.  For example, the following URL shows the List ID as 1082:

    http://client.econnectemail.com/admin/index.php?Page=Subscribers&Action=Manage&Lists[]=1082


SegmentID - a unique number that identifies each contact list segment.  To locate the ID of a segment, log into eConnect Email, and then click the Contact Lists menu, and View Segments.  On the resulting page, find the segment you want, and either hover over or click its View Contacts link; the "Segment=" value in the link's URL is the ID you want.  For example, the following URL shows the Segment ID as 137:

http://client.econnectemail.com/admin/index.php?Page=Subscribers&Action=Manage&Segment=137


CampaignID - a unique number that identifies each email campaign in eConnect Email. You can get an email campaign's ID one of two ways:

  • via the API:  invoke the GetCampaigns method, which will return all email campaigns along with their IDs
     
  • via the eConnect Email application:  login to eConnect Email, and then click the Email Campaigns menu, and View Email Campaigns.  On the resulting page, find the campaign you want, then either hover over or click its View link -- the "id" value in the querystring of the link URL is the ID you need.  For example, the following URL shows the Campaign ID as 1082:

    http://client.econnectemail.com/admin/index.php?Page=Newsletters&Action=View&id=2480


CampaignReportID - a unique number that identifies each campaign report (i.e. the report for each campaign send as seen on the Reports screen).  You can get the ID of a campaign report one of two main ways:

  • via the API:  invoke the GetCampaignReports method, which will return all campaign reports along with their IDs
     
  • via the eConnect Email application:  login to eConnect Email, and then click the Reports menu, and Email Campaign Statistics.  On the resulting page, find the campaign report you like, then either hover over or click its View link -- the "id" value in the querystring of the link URL is the ID you need.  For example, the following URL shows the Campaign Report ID as 1082:

    http://client.econnectemail.com/admin/index.php?Page=Stats&Action=Newsletters&SubAction=ViewSummary&id=6069


CustomFields - API methods such as AddSubscriberWithCustomFields, ModifySubscriberWithCustomFields, and GetSubscriber, take in or return an array of custom field "objects."  Custom field information can be retrieved one of two main ways:

  • from the API:  invoke the GetListDetails method to obtain information about each custom field, including Field ID, name, type, default value, and whether or not the field is required
     
  • from the eConnect Email application:  login to eConnect Email, and then click the Contact Lists menu, and View Custom Fields.  On the resulting page, find the custom field you want, and either hover or click on its Edit link -- the "id" value in the querystring of the link URL is the ID you need.  For example, the following URL shows the Custom Field ID as 534:

    http://client.econnectemail.com/admin/index.php?Page=CustomFields&Action=Edit&id=534

A few notes regarding the handling of custom fields:

  • for custom field types that store single values (text or numbers), data is sent and received through the API as basic string values.
  • the Checkbox fields, since it accepts multiple values, must be able to decipher each value from the single string received through the API.  To accomplish this, separate each checkbox value by a comma, and enclose each value in double quotes.  For instance, for a checkbox field with the values Hiking, Skiing, and Couch Surfing, an instance where all items are checked off would result in a string like this:
         "Hiking","Skiing","Couch Surfing"
    Should any checkbox value have a double quote, simply include the quotes in any checkbox values you provide, and expect that the returned custom field data will do the same.
  • for Date fields, values must be specified in the format YYYY-MM-DD (i.e. year - month - day), to ensure no confusion between month and day values.
  • For Pick List (dropdown) fields, we recommend you specify only values that are contained in the current list of field values. eConnect Email does allow users to change the list of dropdown choices, including renaming, adding, and deleting them. Because of this, eConnect Email will accept current item choices, as well as the original list choices, as long as those original values were retained and simply renamed. In the end, we strongly recommend you keep any code up-to-date with the current list of the field choices.


Status - indicates the current status of a subscriber within a contact list.  Acceptable values include:

  • Active - the subscriber is active and will be sent email sent to the list.  If the subscriber hard bounced or unsubscribed records of that will be purged and they will be treated as an active user again.
  • Bounced - sets the subscribers status to bounced. The subscriber will be treated as a hard bounce and the bounce time will be set to the current time.
  • Unsubscribed - sets the subscribers status to unsubscribed. The subscriber will not be sent an unsubscriber confirmation email and the unsubscribe time will be set to the current time.

When setting the status value, such as through ModifySubscriber or ModifySubscriberWithCustomFields, you can provide any of these values, or leave the value blank to maintain the current setting.