Upload an Address List

Now that we have a document uploaded, it's time to tell the API where you want to send it. This is done using a POST call to the /addressLists endpoint.

Addresses in Click2Mail are contained within Address Lists (also called mailing lists). An address list may consist of a single address, or an arbitrarily large number of addresses, but actions are always taken on a list as a whole. In other words, you don't select individual addresses from a list -- you define lists for the mailing job you want to do. This differs from Address Books, which will be handled later.

Calls to /addressLists differ from most other endpoint POST calls in that there is a single body parameter consisting of an XML block, rather than individual parameters.

The structure of the XML block you send varies depending on how you wish to pass address information. We provide two fairly standard formats that will work for many situations, but you can define your own as well (which is beyond the scope of this tutorial).

The format of the block is declared using the <addressMappingId> tag. Click2Mail provides IDs 1 and 2 for general usage:

Address List Formats

<addressList>
  <addressListName></addressListName>
  <addressMappingId>1</addressMappingId>
  <addresses>
    <address>
        <Firstname></Firstname>
        <Lastname></Lastname>
        <Organization></Organization>
        <Address1></Address1>
        <Address2></Address2>
        <Address3></Address3>
        <City></City>
        <State></State>
        <Postalcode></Postalcode>
        <Country></Country>
    </address>
    <address>
        ...
    </address>
  </addresses>
</addressList

<addressList>
	<addressListName></addressListName>
	<addressMappingId>2</addressMappingId>
	<addresses>
		<address>
			<First_name></First_name>
			<Last_name></Last_name>
			<organization></organization>
			<Address1></Address1>
			<Address2></Address2>
			<City></City>
			<State></State>
			<Zip></Zip>
			<Country_non-US></Country_non-US>
		</address>
		<address>
      ...
		</address>
	</addresses>
</addressList>

The example code below uses addressMappingId 1 to create a single-address address list:

# Load the HTTP requests module
import requests

# Define the endpoint to use
url = "https://stage-rest.click2mail.com/molpro/addressLists"

# Define credentials
myusername = 'awesomeuser'
mypassword = 'gReAt/PaSsWoRd123'

headers = {
    "Accept": "application/xml",
    "Content-Type": "application/xml"
}

# Build the XML block containing the mappingId and the 
# address information
body = (
'<addressList>'
  '<addressListName>My First List</addressListName>'
  '<addressMappingId>1</addressMappingId>'
  '<addresses>'
    '<address>'
        '<Firstname>Awesome</Firstname>'
        '<Lastname>User</Lastname>'
        '<Organization>Justice League</Organization>'
        '<Address1>715 S Calhounne St</Address1>'
        '<Address2></Address2>'
        '<Address3></Address3>'
        '<City>Terra Firma</City>'
        '<State>IN</State>'
        '<Postalcode>46802</Postalcode>'
        '<Country></Country>'
    '</address>'
  '</addresses>'
'</addressList>'
)

# Make the POST call
r = requests.post(url, data=body, headers=headers, auth=(myusername, mypassword))

# Display the result - a success should return status_code 201
print(r.status_code)

# Display the full XML returned.
print(r.text)

On a successful add, the returned data should look similar to the following. Note the returned <id> value, which is the address list's ID :

200
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addressList>
  <id>472743</id>
  <status>3</status>
  <description>CASS Standardized</description>
  <statusLocation>http://stage-rest.click2mail.com/molpro/addressLists/472743</statusLocation>
</addressList>

HTTP Return Codes And Possible Statuses

HTTP Response	Status	Description
200	0	Uploaded / Created
200	1	Mapped
200	3	CASS Standardized → this status means address list is ready for use in jobs
200	9	Error
400	9	Invalid input data

HTTP Response 500. If you get a 500 response please contact Click2Mail customer support.