dotCal Mail Help For XML

dotCal XML interface Help

Automatic XML Post http://emailer.dotcal.com/dbadmin/kbase.pl

Sending data to our XML API requires that you use a scripting language to post to scripts on our server. Languages like Perl, PHP, ASP, .NET, Java, and C++ all provide for user agents that will send form data in HTTPS POST format to our server. We strongly recommend that you use HTTPS POST (and not GET) so you aren't limited by the size of the XML commands.

Please note that due to the technical nature of the XML API, we do not offer free support for this feature. The cost to troubleshoot and make any corrections to your XML is $100 minimum and $100 per hour after the first hour. We do not troubleshoot the code that generates your XML, but only your XML, and will need the XML you are experiencing difficulties with emailed to us at Dan@neutralspace.com, along with your acknowledgment and acceptance of the support charges.

You can POST data to your account automatically using our XML API from an external script with this:

https://emailer.dotcal.com/dbadmin/xml_post.pl

You will only need to send data by HTTPS POST with these names (these must match exactly and they are case-sensitive):

username
api_password
xml_body

Important Notes:

In order to make use of this API you must set your API password and enable API access on the My Account -> Change Password page.
It is strongly recommended that you POST to us via SSL encrypted HTTPS and not using plaintext HTTP methods

The XML datastream has 5 top-level data types:

<Record> for uploading contact information,
<Edition> for uploading edition content,
<ListSettings> for updating list settings
<LinkLibrary> for uploading links into your Link Library, and
<Send> to use XML to send emails and broadcast to your lists

Working with Editions

The <Edition> is used for uploading edition content to a list and edition in your dotCal mail account. There are 5 types of data that go with each edition - EditionName, EditionSubject, EditionList, EditionHTML, EditionText, and ArchiveEdition. ArchiveEdition can be either 'Add' or 'Remove'.

An example record might look like this:

<Edition> <EditionName>someEditionName</EditionName> <EditionSubject>Subject line of your email</EditionSubject> <EditionList>MailingListName</EditionList> <EditionHTML><html><body> This is just a test. </body> </html> </EditionHTML> <EditionText>Some sample text here</EditionText> <ArchiveEdition>Add</ArchiveEdition> </Edition>

Working with List Settings

You can define List Settings using a specific set of commands. Each list setting you define must exactly match the database field for the setting. The basic command structure is like this:

<ListSettings List="listname"> <Field>field value</Field> </ListSettings>

Available Field names are (note - these are case-sensitive):

Company (From name)
Email (From email)
Admin_Email (administrative email
PhysicalAddress1 (first line of street address)
PhysicalAddress2 (second line of street address
BlankUnsubEmail (receive confirmation of unsubscribes if no comments, can be "on" (yes) or null value (no))
listtype (public, private, or secret (secret is what the database calls a hidden list))
listdesc (short description of list)
profileLayout (Classic, Modern, or Vertical - the unsubscribe/profile update page layout)
listupdatefields - a comma-delimited list of all the fields that can be updated on the profile update page
ProfileUpdateThankYou - URL of a page the user is directed to after the profile update is complete
unsubscribe_on - the footer of the email. Can be headerfooter (header and footer #1), on (footer #1 only), headerfooter2 (header and footer #2), footer2 (footer #2 only), or null (no footer, but this only works on lists of under 100 contacts).
footerLanguage - English, Espanol, or Francais
FooterBackground - White, Gray, or Transparent
listowner - used in the footer
bannerlink - if you specify a Banner for this list, it will link to this URL
send2friend - the send-to-a-friend in the footer of the email. Can be Large (form), Small (small form), Link, Link Colleague (send to a colleague), or None.
send2friendForm - default language in the Large send-to-a-friend form
send2friendURL - URL the referrer is directed to after sending to a friend
send2friendMessage - custom message to the friend
query_strings - track query strings in links. Can be 'yes' if on, or blank (null) if off.
charset - character set of email (iso-8859-1, utf-8, utf-16, us-ascii, iso-2022-jp, iso-8859-2, iso-8859-5, iso-8859-7, iso-8859-8, gb2312, big5, iso-2022-kr)
Font - default font
Fontsize - default font size
underline - underline links. Can be 'hover' (only underline on mouseovers), 'always', or blank (null) to turn off underlining links.
bordercolor - border around the email. Can be any HTML color or 'None' if no border.
Textcolor - default color of text
Forecolor - default link color
Overcolor - default link mouseover color
Backcolor - default color of stationery (note that the Background and Stationery color and image field names are switched from their actual roles)
BgImage - complete <img> tag of a stationery graphic
Statcolor - default color of background behind email
StatImage - complete <img> tag of the background behind the email
Banner - complete <img> tag of the banner
Logo - complete <img> tag of the logo

Working with Contacts

For the <Record> datatype, the fields you pass up must correlate exactly with the Master List fields. For more information, look at the Knowledge Base entry for "Master List Import XML".

The uploaded file must be a text/plain format, and it must look something like this:

<Record> <Email>person@somesite.com</Email> <Firstname>Mary</Firstname> <Lastname>Jones</Lastname> <MailingLists>List1,List2,List3</MailingLists> </Record>

You can upload as many records as you like, and each record can have any or all of the field names you see in the Detailed View of each contact in the Master List (e.g., "Email", "Firstname","Company","User1","Notes", etc).

Managing a Contact's Subscribed Lists

You can manage the Mailing Lists a contact is subscribed to by using one of the following 3 XML Tags, which are described in more detail below.

<MailingLists> -- Define the entire set of Mailing Lists. <AddLists> -- Add to a contact's set of subscribed Mailing Lists. <DropLists> -- Remove from a contact's set of subscribed Mailing Lists. Note: You can only specify one of the above tags per record.

Adding Contact to Lists

When you upload a <MailingLists> field for a contact, it will re-define the lists that contact is assigned to. You may want to just be able to add a contact to a list if that contact is not already on the list. Use the <AddLists> command like this:

This will add the contact to List1 and List2 if the contact is not already on those lists.

Dropping Contact From Lists

To remove someone from a Mailing List, all you have to do is include this XML in the Record data:

Setting a Contact's Lists

Instead of adding to, or removing from a contact's subscribed lists you can specify the list in its entirety. To set all the lists a contact is subscribed to, all you have to do is include this XML in the Record data:

This will set the contact to List1, List2 and List3 regardless of which lists the contact was previously set to.

Removing a Contact Completely

You can remove a record from the MasterCRM completely with the ClearRecord command. Note that you can't remove Unsubscribed contacts from the CRM with this (this is to protect you from accidentally sending to this contact). It would look like this:

<Record> <Email>someone@something.com</Email> <ClearRecord>1</ClearRecord> </Record>

Changing a Contact's Email Address

Because dotCal mail uses the email address as the primary key for each contact, you must use a separate command inside the <Record> tags to change a contact. The XML command is ChangeEmail, and it would look something like this:

<Email>someone@something.com</Email> <ChangeEmail>someone@another.com</ChangeEmail> </Record>

Event Triggers

To have an email sent immediately to the person you are posting, add this tag:

<Trigger>List_Edition</Trigger>

You can even add delayed event triggers like this:

<Event1date>04/15/2002</Event1date> <Event1listedition>somelist_youredition</Event1listedition>

Note: format the the Event#date field is either MM/DD/YYYY or is an integer that represents the delay in the number of days for the triggered email (autoresponder). You can also make the event trigger look like this (this example is a 3-day delayed autoresponder):

<Event1date>3</Event1date> <Event1listedition>somelist_anotheredition</Event1listedition>

You can also remove events for a contact if you set the event's date field to be "Remove" like this:

<Event1date>Remove</Event1date> <Event1listedition>somelist_anotheredition</Event1listedition>

By default dotCal mail will not send an autoresponder email to the same person twice. We automatically run a de-duplication to verify the contact only receives one particular edition. You can override this with this XML tag:

Activities - Option 1 (preferred)

You can use XML to add activities to the Master CRM. This is done very simply, like this:

<Activity id="1">200308131530|Meeting|test description more information here and more information about the activity here. |test status </Activity>

Each activity element (Date|Activity|Description|Status) is uploaded in a pipe-delimited list, with each separate activity delimited by a newline. Date is in the format YYYYMMDDhhmm, Activity must be one of the Activities you have defined in your Master CRM, and Description and Status can be any text field you would like (limit of 1k per field).

Activities - Option 2

The other way to add activities requires that you have NO newlines (carriage returns) in your activities. This is done like this (note the plural "Activities" is used in Option 2):

Link Library

Adding a link to the Link Library is very simple - just put the link between LinkLibrary tags like this:

<LinkLibrary>http://www.somesite.com/somepage.html</LinkLibrary>

If the link does not already exist in the Link Library, it will be added.

Create A New Mailing List

Use the <NewList> command to create a new mailing list. Each list created must have an edition in it. The XML command looks like this:

<NewList FirstEdition="editionName">MailingListName</NewList>

Redefine a Mailing List

You can use the <DefineMailingList> function to redefine the contacts in a specific mailing list. Anyone not in the list of email addresses provided will be dropped, and anyone in the uploaded list that isn't in the mailing list will be added. This function is called like this:

<DefineMailingList list="listname"> <Email>something@somesite.com</Email> <Email>another@anotherone.com</Email> </DefineMailingList>

Sending Messages

To use XML to send messages with dotCal mail, you can use the XML <Send> command to send either test messages or broadcasts. The generic format of the XML <Send> is as follows:

<Send List="listname" Edition="editionname">RECIPIENT COMMAND</Send>

RECIPIENT COMMAND specifies who you want to send the edition to. Commands fall into two categories - specific recipients and broadcasts.

If you would like to send to a specific list of email addresses, put those email addresses (comma delimited) between the <Send></Send> like this:

<Send List="listname" Edition="editionname">person@something.com,another@somesite.com</Send>

If you would like to broadcast to the mailing list, you have 3 options:

Broadcast All - sends to all members of the list, regardless of whether they have already received this edition
Broadcast Unsent - sends to all members of the list who have not yet received this edition
Broadcast ### - sends to ### random recipients who have not yet received this edition

An example of this would be:

<Send List="listname" Edition="editionname">Broadcast 200</Send>

The above example would send the edition "editionname" from the list "listname" to 200 random people who have not yet received it.

An important note: By using this XML API to send emails, you have incredible power to send emails to a lot of people. Be absolutely sure you have tested your interface thoroughly before you create a production environment on your side. If in doubt, please contact our technical support department. To be able to use this function, your account must be in good standing.

Another Note - we run our broadcast queues every 20 minutes, so allow for some delay from when you send up the broadcast to actual delivery of your messages.

Server Response

The server will provide you with XML information about your upload. The response fields below are defined:

Compiled - the script successfully compiled without error
DBConnect - successfully connected to your dotCal mail account's database
EditionSuccess - successfully uploaded the edition content into the proper mailing list
EditionFailure - did not successfully upload the edition
ImportRecords - the number of separate records identified in the incoming file
ExistingRecords - the number of contacts currently in your Master List
Invalid Email - this will be created every time an invalid email address is sent; each email address will get its own tag
Completed - this is counted in increments of 100 to give you an ongoing count of uploaded records as the script is running
FinalCompleted - the total number of records successfully added or modified
Duplicates - the number of email addresses found in your XML upload that already existed in the Master List (another way to say this is the number of modifications made to the Master List)
InvalidLists - the number of contacts uploaded where mailing lists that were not added to due to because the mailing lists didn't exist
Triggers - the number of triggered emails (autoresponders, or Master CRM events) set with this upload

As an example,a successful upload of a contact record would look something like this:

<Compiled>Yes</Compiled> <DBConnect>OK</DBConnect> <EditionSuccess>MailingListName_someEditionName</EditionSuccess> <ImportRecords>1</ImportRecords> <ExistingRecords>1526</ExistingRecords> <FinalCompleted>1</FinalCompleted> <Duplicates>1</Duplicates> <InvalidLists>0</InvalidLists> <Triggers></Triggers> <XMLUpload>Complete</XMLUpload>

Note that some optional fields will be added if you uploaded autoresponders or activities:

The response for uploading links to the Link Library is just the number of successfully added links:

If you are use the <NewList> function to create a new mailing list, the response from the server will confirm new lists that have been created. This will be in this XML format:

If you are using the <DefineMailingLists> function, you will get these responses back:

If you defined list settings with the <ListSettings> command, you will get a response for each list you updated that looks like this:

<ListSettingsUpdated List="listname">field1,field2,field3</ListSettingsUpdated>

Where field1, field2, etc are the fields you updated.

If you have used the <Send> command to send emails or broadcasts, you will get a response like this:

<Send List="testlist" Edition="editionname" Recipients="1">Successful</Send>

If there's an error in the send, the response from the server will be like this:

<SendError>HTTP Response From Server</SendError>

Portal Managers

The PortalCommand function allows the Portal Manager to update individual accounts by XML. Currently it is limited to setting the Emails included in the account's plan, and the anniversary (expiry YYYYMM) of the account.

<PortalCommand> <Username Exports="#" Anniversary="YYYYMM" Active="ActiveSetting" Branding="BrandingSetting" Monthly_Payment="#">username</Username> </PortalCommand>

You have the following options for setting the Active value:

Active - Client is active and paying you
Declined - Client's credit card was declined by the bank
Canceled - Client canceled account
Comp1 - a comped account with no CRM access
Comp2 - a comped account with full access
Scheduled for Deletion - at 1am Pacific Time (US) this account will be deleted by an automatic script we run every 24 hours

You have the following options when setting Branding:

None - no footer. This is very dangerous and will require that you trust the client to insert their unsubscribe link into the creative
Minimum Unbranded - no "powered by" and you product name is not mentioned in the footer of the outgoing email
Minimum Branded - no "powered by", but your product name IS mentioned in the footer
Standard Textonly - a "powered by" link is at the bottom of the client's messages, and your product name is mentioned in the footer
Standard Image - your "powered by" image is at the bottom of the client's messages, and your product name is mentioned in the client's message footer

Each account that is updated will count for the final confirmation of updated accounts, sent back in the HTTP response from our server

XML Retrieve Version 2 http://emailer.dotcal.com/dbadmin/kbase.pl

This Knowledge Base item is for the XML Retrieve function, Version 2.1

The XML API provides for a way for an external program to pull down data from the dotCal mail database. To access the XML data, send via HTTP POST or HTTPS POST (the useage of SSL encrypted HTTPS is strongly encouraged) to the following URL:

https://emailer.dotcal.com/dbadmin/xml_retrieve2.pl

The following name/value pairs are sent to this URL (these are case-sensitive):

username (required)
api_password (required -- set this on My Account -> Change Password page)
mailinglist
edition (if you specify this, you must specify a mailinglist)
contact (if you specify this, you must specify either a mailinglist, or set allLists to a non zero value, if you want sent/read/click data)
searchfield and searchvalue - if you want to search the CRM database
EditionData (if you specify this, you will only get the actual email edition)
ListSettings - if you define this to any nonblank value, you will get the list settings for the mailing list specified above
readstamp - if set to any nonzero value, this will return the datetime stamp of the reads instead of just the number of reads for an edition. Format is YYYYMMDDhh, and XML for each Read will look like this: <Read Format="YYYYMMDDHH">2003102101</Read>
readstampfull - if set to any nonzero value, this will return the datetime stamp, including minutes, of the reads instead of just the number of reads for an edition. Format is YYYYMMDDhhmm, and XML for each Read will look like this: <Read Format="YYYYMMDDHHMM">200310210115</Read> If both readstampfull and readstamp are set, readstamp will be ignored.
Events - if set to any nonzero value, displays any events (delayed emails or autoresponders) along with the record data
getUserFieldDefinitions - if set to any nonzero value, will return the user-defined field settings from the account's MasterCRM
SuppressContacts - if you define "mailinglist", and want to suppress the contacts from that list (i.e., if you only want ListSettings), you can set SuppressContacts to be any nonzero value
SuppressContactData - if set to any nonzero value, all contact data except the email address will be suppressed.
allLists - if you define "contact", and do not specify a mailinglist, you may set this to a nonzero value to receive send/read/click data across all lists to which contact is subscribed.

The last 3 POST options serve as a way for you to narrow down the data you want returned. By specifying the mailinglist, you will retrieve data for only those contacts on that particular mailing list. By specifying the edition, you are further refining the sent/read/click data for that contact to only one specific edition; please note that you must specify which mailing list this edition is in. By specifying a contact, you are retrieving data only for that particular contact.
If you do not specify a mailinglist, edition, or contact, you will only receive Master CRM data.

Returned data comes in two parts - Master CRM data, and sent/read/click data.

The Master CRM data will return valid XML fields for any fields that have non-null values (i.e., a blank field will not be in the XML stream, to save space).Similarly, if a recipient did not click on a link, you will not see a blank XML field. To be in compliance with the XML spec, we convert any <>'&" characters in the Master CRM data in this field to their HTML equivalents (< becomes < and > becomes > and ' becomes ' and " becomes " and & becomes &).

An example of a returned XML datastream is below:
<Retrieve>
<Record>
<rec>523</rec>
<Email>someone@somecompany.com</Email>
<Firstname>Joe</Firstname>
<Lastname>Somebody</Lastname>
<Company>Some Company</Company>
<User1>some data here</User1>
<User2>We'll put more data here</User2>
<Notes>And we'll put more notes here</Notes>
<Edition Name="SomeEdition">
<Sent Format="YYYYMMDDhhmm">20030913143010</Sent>
<Read>5</Read>
<Click URL="http://www.somelink.com">3</Click>
<Click URL="http://www.anotherlink.com/page.htm">1</Click>
<S2F>2</S2F>
</Edition>
<Event id="1" ListEdition="somelist_someedition" Date="2003-Nov-11">Sent</Event>
</Record>
</Retrieve>

In the above example, you can see the Master CRM data first (starting with the rec, a unique number assigned to the contact, and then ending at the Notes field), followed by the sent/read/click data. In this example, the contact was sent the edition named "SomeEdition" once on Sept 13th, 2003 at 14:30:10 (2:30pm) Pacific Time. (note that the Format option inside the tag tells you we have a datetime stamp - if there is no Format option, we did not record a datetime stamp for the edition). The contact read the edition 5 times, clicked on the link to "www.somelink.com" 3 times and the link to "www.anotherlink.com/page.htm" once, and forwarded it to 2 friends using the "Send to A Friend" form at the bottom of the email edition.

Note that a bounce or unsubscribe is treated a little differently (the following examples will only show up if this specific edition caused a bounce or unsubscribe action from the recipient):
<Bounce></Bounce>
or
<Bounce>A</Bounce>
or
<Unsub></Unsub>

In the top Bounce example, there was no Bounce code provided; in the second example, there is a bounce code. For more information on Bounce codes, search the Knowledge Base or click the "Tips" button on the Contacts page for any mailing list.

If there was a problem with your HTTP POST operation, you will see a response like this:
<Retrieve>
<ErrorCode>#</ErrorCode>
</Retrieve>

In the above example, the number sign (#) designates an error code:

An ErrorCode of 1 means an invalid username/password was provided.
An ErrorCode of 2 means an invalid mailinglist was provided.
An ErrorCode of 3 means an invalid edition was provided.

Note that if you POST a 'contact' that is not in the database, you will get no data back (it does not generate an error). This is also similar if you do a search, where you specify the searchfield and searchvalue - if no match is found, no data will be returned. Also note that you can only POST a "contact" field OR a "searchfield/searchvalue" combination (not both).

Edition Content Data
Edition content will be returned based on how the email will be rendered (in HTML format if there is an HTML version, and in text format if it is a text-only message). Most of it is self-explanatory.

The retrieved XML data will come in text/plain format and will look like this:
<Retrieve>
<EditionData ListEdition="List_Edition">EDITION CONTENT HERE</EditionData>
</Retrieve>

As a reference, below are all of the fields in the Master CRM table:
Email
Firstname
Lastname
Position
Company
Address
City
State
Zip
Phone
Mobile
Fax
Website
Country
EmailFormat (Note: this is one word)
Occupation
Age
Birthday
Income
Gender
User1
User2
User3
User4
User5
User6
User7
User8
User9
etc... through User50
Notes
MailingLists
Lastmod (Datetime of last modification)

ListSettings
The List Settings for a mailing list can be retrieved by specifying this in the posted form data. Each field is pulled directly from the database table for the list. As such, some field names may not be completely intuitive. Most notably, the "Company" field is the "From" email address (aka the Contact Email). A typical XML retrieve stream will look like this:
<ListSettings List="listname">
<Email>fromemailaddr@something.com</Email>
<Company>From Name Here</Company>
etc...
</ListSettings>
A complete list of available fields is given in the XML Post instructions.

getUserFieldDefinitions
The User1-User50 fields defined in the account's MasterCRM can be retrieved in XML format here. This is an example of the User Field Definitions stream:
<UserFieldDefinitions>
<UserField Field="User1" Type="Text">Some user-defined description of User1</UserField>
<UserField Field="User2" Type="Text">A user-defined description of User2</UserField>
etc... through User50
</UserFieldDefinitions>

Possible Types for user fields are "Text", "LongText", "Select", and "Checkbox"

Portal Managers
This function allows the Portal Manager account to download relevant account data via XML. By supplying the HTTP POST name/value pair of "portal" -> "yes" it will indicate to the dotCal mail server to provide this XML data for each account like this:
<PortalData>
<AccountData Username="USERNAME">
<ActiveStatus>Active|Comp|Trial|Canceled|Declined</ActiveStatus>
<PaymentAmount>##.##</PaymentAmount>
<IncludedEmails>#</IncludedEmails>
<Anniversary>YYYYMM</Anniversary>
<ThisMonthSent>#</ThisMonthSent>
<LastMonthSent>#</LastMonthSent>
<TwoMonthsBackSent>#</TwoMonthsBackSent>
<Notes>NOTES</Notes>
</AccountData>
</PortalData>

Note that PaymentAmount will only be supplied if the account is listed as "Active"

Using PHP to HTTP Post http://emailer.dotcal.com/dbadmin/kbase.pl

NOTE: In order to use the XML API you must set an api_password and enable the API from the My Account - Change Password screen.

If you are using PHP to post HTTP data to our scripts, the cURL library is a good way to do it. Some instances of opening sockets to our servers have found to be unreliable due to firewall limitations for security and protecting your data.

The following is an example of PHP using cURL to send an HTTP POST to our server (in this particular case it's the XML command to change an existing email address in the CRM):

<?php

function http_post($server, $port, $url, $vars) {
$urlencoded = "";
while (list($key,$value) = each($vars))
$urlencoded.= urlencode($key) . "=" . urlencode($value) . "&";
$urlencoded = substr($urlencoded,0,-1);

$ch = curl_init ($server.$url);
curl_setopt ($ch, CURLOPT_POST, 1);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $urlencoded);
ob_start();
curl_exec ($ch);
$result=ob_get_contents();
ob_end_clean();
curl_close($ch);
return($result);
}

$username = 'username';
$api_password = 'api_password';
$xmlBody = '<Record>';
$xmlBody .= '<Email>someone@something.com</Email>';
$xmlBody .= '<ChangeEmail>someone@another.com</ChangeEmail>';
$xmlBody .= '</Record>';

$result = http_post("http://emailer.dotcal.com", 80, "/dbadmin/xml_post.pl", array("username"=>$username, "api_password"=>$api_password, "xml_body"=>$xmlBody));

?>

And the followiong is an example of PHP using cURL to do the XML Retrieve function:
<?php
// Get data from dotCal mail server database
function http_get($server, $port, $url, $vars) {
global $data;
$urlencoded = "";
while (list($key,$value) = each($vars))
$urlencoded.= urlencode($key) . "=" . urlencode($value) . "&";
$urlencoded = substr($urlencoded,0,-1);

$ch = curl_init ($server.$url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt ($ch, CURLOPT_POST, 1);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $urlencoded);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($ch, CURLOPT_REFERER, "http://dLogistics-Group.com/autoFill/getInfo.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
ob_start();
$data = curl_exec ($ch);
$result= ob_get_contents();
ob_end_clean();
curl_close($ch);
return($result);
}

// Get user info from dotCal mail
$resultRetrieve = http_get("http://emailer.dotcal.com", 80, "/dbadmin/xml_retrieve2.pl", array("username"=>$username, "api_password"=>$api_password, "mailinglist"=>$mailingList, "contact"=>$userEmail));
//echo $data . "<br>";

//parse through user data to extract form fields
if (!$doc = domxml_open_mem("<?xml version='1.0' encoding='ISO-8859-1'?>" . $data)) {
echo "Error parsing XML!";
}

$root = $doc->root();
$children = $root->children();
foreach ($children as $child) {
$record = $child->children();

if ($child->tagname == 'Record') {
foreach ($record as $field) {
$formFields = $field->children();

if ($field->tagname == 'rec') {
$tag = $field->children();
$rec = $tag[0]->content;
}

// etc.

}
}
}

?>

Master List Import XML http://emailer.dotcal.com/dbadmin/kbase.pl

Using XML to import into dotCal mail allows for a simple, effective way to upload contact information into your Master List.

The uploaded file must be a text/plain format, and it must look something like this:

<Record>
<Email>person@somesite.com<Email>
<Firstname>Mary</Firstname>
<Lastname>Jones</Lastname>
<MailingLists>List1,List2</MailingLists>
</Record>

You can upload as many records as you like, and each record can have any or all of the field names you see in the Detailed View of each contact in the Master List (e.g., "Email", "Firstname","Company","User1","Notes", etc).

Using VB.NET to HTTP POST http://emailer.dotcal.com/dbadmin/kbase.pl

If you are using Visual Basic .NET architecture to connect to dotCal mail with XML, the following code snippet may help you:

Dim web As New System.Net.WebClient ' Holds the Web Object to Connect toWeb Server
Dim PostString As String ' Holds the Formatted Post String
Dim WebResult As String ' Holds the Result String
Dim baPostData As Byte() ' Holds the Post String in Byte Array
Dim baResult As Byte() ' Holds the Result in Byte Array

' Start formating Post String as required
PostString = PostString & "username=" & UserName
PostString = PostString & ";password=" & Password
PostString = PostString & ";xml_body=" & xml_body

web.Headers.Add("Content-Type", "application/x-www-form-urlencoded")

'Convert Post String to Byte Array
baPostData = System.Text.Encoding.ASCII.GetBytes(PostString)

Try

'Make a Post to Web Site URL
baResult = web.UploadData("http://anywebsite.com/anypage.ext", "POST",baPostData)

Catch ex As Exception ' catch the Web Exception and deal separately
Throw New Exception("Exception Catch", ex)
End Try ' Convert the Byte Array result back to String

WebResult = System.Text.Encoding.ASCII.GetString(baResult)

PostString = Nothing
WebResult = Nothing
baPostData = Nothing
baResult = Nothing
web.Dispose()
web = Nothing

On Profile Update Post XML http://emailer.dotcal.com/dbadmin/kbase.pl

You can elect to have XML data of changes made via automatic profile update sent to your server via HTTP POST. On the Update Account page (under the My Account tab), in the Account Configuration area, simply enter the URL you would like the data posted to. Data will be sent in this format:

<Record Username="your dotCal mail username" Email="recipient's email">
<CRM Field>New Field Value</CRM Field>
</Record>

The CRM field in the example above corresponds to any field in your Master CRM (Firstname, Lastname, Company, User1, etc).

XML Editions List http://emailer.dotcal.com/dbadmin/kbase.pl

You can use an automatic XML retriever to get the lists and editions in an account. Use SSL encrypted HTTPS POST to send username, api_password, and (optional) list name to return all of the editions in an account. If you pass the list name, it will return only the editions in that list.

Post this data to http://emailer.dotcal.com/dbadmin/xml_editions.ice

Username
api_password (set this on the My Account -> Change Password page)
List name (optional)

The response from the server will look like this:

<List Name="ListName" ListType="listtype" ListDescription="user-defined description">
<Edition>Some Edition Name</Edition>
<Edition>Another Edition</Edition>
</List>
etc for all your lists...

ListType will be public, private, or hidden. The ListDescription is defined by the user the List Settings screen for that list.