TclMML

[mml upload mailing_list]

Documentation: Uploading Mailing Lists

[ Home | Docs | FAQ | Download | CVS | Mailing Lists | Bug Tracker | USPS's MOL Site ]

Syntax

mml upload mailing_list ?-flags? ?-switches? mailing_list_name

Flags

-only_if_not_found (Optional)

This flag indicates that the document should only be uploaded if an existing mailing list with the same $mailing_list_name does not exist.

-keep_all (Optional)

This flag indicates that the MOL system should commit all addresses, even those that are not in standard format. This flag cannot be combined with -delete_non_std.

-delete_non_std (Optional)

This flag indicates that the MOL system should commit only those addresses that are in standard format. This flag cannot be combined with -keep_all.

Switches

-debug filename (Optional)

If specified, the XML generated and sent to the MOL system, as well as the XML reply from the MOL system, will be appended to filename.

-data data (Required Alt.)

Use this switch to provide the $data to be uploaded. This switch is mutually exclusive with -file.

-file filename (Required Alt.)

Use this switch to specify that the contents of filename are to be read & uploaded. This switch is mutually exclusive with -data.

-mappings field_mappings (Optional)

This switch specifies how the MOL system should interpret the columns of data in the mailing list that is being uploaded. $field_mappings should contain a list of key/value pairs, as in the format returned by the Tcl [array get] command, where the key is the name of the MOL/MML element being mapped to, and value is the name of the column in your mailing list.

Here is a list of MOL/MML address elements you can map your maililing list to:

  • title
  • prefix
  • fullname
  • firstname
  • middlename
  • lastname
  • suffix
  • company
  • addressline1
  • addressline2
  • urbancode
  • city
  • state
  • country
  • postcode

At a minimum, if you provide a mapping, you should map either fullname or firstname & lastname along with addressline1, city, state and postcode.

Your mailing list can have additional columns that are not mapped to MOL/MML fields (such as those that you'll use in mail-merge documents).

Positional Arguments

mailing_list_name

This is an arbitrary text string used to name the mailing list. The MOL system requires document_name to be unique; however, if a duplicate is used, MOL (appears to) append a counter suffix of sorts.

Return Value

If successful the mailing_list_id assigned by the MOL system is returned. This is an opaque value used to identify the document in subsequent actions (i.e., mailing_list details, delete mailing_list, and upload order).

An error will be returned if the document upload was not succesful. Possible causes under which an error could be raised include: transient network outages, MOL processor internal errors, uploading of a mailing list in a format that the MOL system does not know how to process, etc.

Notes

Before you use your uploaded mailing list to place an order you must provide a mapping to the MOL system of your columns to their address fields. However, you can do this after the mailing list has been uploaded via href map mailing_list.

If you do not provide a mapping, then the -keep_all and -delete_non_std are ignored (since the MOL system won't know which columns make up the address data, it won't be able to tell which addresses are in standard format and which aren't).