API Documents

Connect your Website or Software to Direct Mail Manager!

The Small Business Web Logo Attention Developers! Now you can offer automated direct mail to your customers or integrate with your website, web app or software. Our API allows you to carry over many of the items available in our Campaign Management area. Only programmers need apply since API Integrations can be serious stuff, but we have made our API simple and powerful.

Basic Details:

Our API gives you all the tools needed to import mailing lists to us and retrieve customer order information back to your system if needed. Our API returns XML when when given an action and data via an HTTP POST. These standard methods allow for language/environment flexibility and faster development times for you. API connections can be set up for Direct Mail Manager On-Demand Direct Mail, Private Label (M3) Web-To-Print-Mail Stores, Postcard Services and for 2ndShot Automated Mail.

Before You Get Started:

Before you jump in and start connecting to us, you want to take some time to determine what your integration will be designed to do. Will you be mailing addresses to an existing campaign in Direct Mail Manager or will you be sending a completed CSV data file? Will you be selling direct mail at your own price and have Postcard Services run invisible in the background? Take some time to review your project and feel free to email adam@postcardservices.com to start a discussion about your project. This will save you unnecessary development time and a much smoother integration.

FTP Option:

A very simple way to connect to our system is through private FTP and our 2ndShot Automated Mail system . If you are sending direct mail on an on-going basis this is a pain free way to set up an on-going campaign. For example you have 100 customers signing up a day on your website and you want to mail them a postcard automatically, this will work well for you. Our 2ndShot Automated Mail system can pull all the list data (sent via FTP or via API) and all the artwork required for printing and mailing from one FTP folder. Variable Data direct mail (mail with artwork or text specific to the recipient) also works best with FTP. Please call 866-571-3111 for more information if you would like to use this method.

Implementation Details:

API uses delivers XML information when requested via an HTTP POST request to mgapi.asp
All API Methods Require:

  • API KEY (field name: apikey) - Key provided for accessing API
  • Customer ID (field name: idcust) - Customer # - Provided with API Key
  • Action (field name: action) - Action Requested - More Documentation Below

API Test Area

We have set up a tool for you to test your API connection.

Click Here

Valid API Action Values

  • addcustomer - Creates new customer account, requires customeremail value and optionally takes any of the field names returned by the listcustomer action, along with password
  • updatecustomer - Same as addcustomer, but updates existing customer
  • changepassword - Change a password for an account. Works the same as addcustomer and updatecustomer, but requires only customeremail and password values.
  • changeemail - Change an email address for an existing account. Requires customeremail for current email address and newemail for the email address to update to
  • listcards - Lists cards for a customer. Requires customeremail
  • dmmaddlead - Create a list with a single lead. Overwrites an existing list if it exists. Requires customeremail
  • dmmaddleads - Create list with multiple leads. Overwrites an existing list if it exists. Requires customeremail and orderno
  • getdmmfunds - Returns the Account Balance for a Campaign Customer
  • getdmmcampaigns - Returns the Campaigns for a Campaign Customer
  • attachimage - Attaches an Image to an Order or Campaign
  • dmmmaillist - Triggers for mailing an existing list to an existing campaign
  • dmmaddleadandmail - Create a list with a single lead and then submits the lead for mailing. Overwrites an existing list if it exists. Requires customeremail and orderno
  • dmmaddleadsandmail - Create list with multiple leads and submits the list for mailing. Overwrites an existing list if it exists. Requires customeremail and orderno
  • SetLowBalanceWarningAmt - Sets the Low Balance Warning Amount Level. When orders are placed and the account balance is below this level, a low balance warning amount email is sent to the customer.

AddCustomer Action:

The API Add Customer Action allows you to create a new customer account.

The following are field names that will be accepted by the API when creating a customer. customeremail is the only required field.

  • customeremail
  • firstname
  • lastname
  • company
  • phone
  • address
  • city
  • state
  • country
  • zip
  • comments
  • password
  • shippingfirstname
  • shippinglastname
  • shippingphone
  • shippingaddress
  • shippingcity
  • shippingstate
  • shippingcountry
  • shippingzip

Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&action=addcustomer&customeremail=yourcustomer@yoursite.com&firstname=John&lastname=Smith&address=123 Fake St&city=Springfield&state=IL&zip=12345&phone=123-456-7890&company=ABC Products

An XML response is returned. If successful the response should look like
 <MGRESPONSE><OK>Update Ok</OK></MGRESPONSE>

Failure will produce an error like

 <MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors



UpdateCustomer Action:

The API Update Customer Action updates and existing customer record within your account.

The required fields and the output of the UpdateCustomer action are the same as the addcustomer action.

ChangePassword Action:

The API Change Password Action allows you to change the password of customer within your account.

The following are fields are required

  • customeremail
  • password

Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&action=changepassword&customeremail=testuser@yoursite.com&password=yourpassword

An XML response is returned. If successful the response should look like
<MGRESPONSE><OK>Update Ok</OK></MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors



ChangeEmail Action:

The API Change Email Action allows you to change the email address of customer within your account.

The following are fields are required. customeremail is the current email address for the customer, newemail is the email address to update the customer record to.

  • customeremail
  • newemail

Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&action=changepassword&customeremail=testuser@yoursite.com&newemail=newaddress@yoursite.com

An XML response is returned. If successful the response should look like
<MGRESPONSE><OK>Update Ok</OK></MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors



ListCards Action:

Allows you to get a list of card designs for a customer within your account

The following are field is required by the API when requesting a list of card designs

  • customeremail

Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&action=getactivecampaigns&customeremail=yourcustomer@yoursite.com

An XML response is returned. If successful the response should look like
<MGRESPONSE>
<CARD>
 <ID> 12345 </ID>
 <JPGFRONT> URL </JPGFRONT>
 <JPGBACK> URL </JPGBACK>
 <NAME> My Card Design </NAME>
 <APPROVED> YES </APPROVED>
 <PDF> URL </PDF>
 <SIZE> 4 x 6 </SIZE>
 </CARD>
</MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors



DMMAddLead Action:

The API Add Lead Action allows you to send a single mailing list line from your system to Postcard Services. The add lead method will create or overwrite a lead list file with a single line which can processed. A List Name is required. The list will be available in the lists on the campaigns screen.

A customer email address is required as an input field. This is the customer's email address on the account not the lead's email address

  • customeremail

The following are field names that will be accepted by the API when adding a lead

  • ListName
  • orderno
  • name
  • company
  • address1
  • address2
  • city
  • state
  • zip
  • phone

Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&orderno=123&customeremail=accountemail@yoursite.com&action=dmmaddlead&listname=mylist.csv&name=John Smith&address1=123 Fake St&city=Springfield&state=IL&zip=12345&phone=123-456-7890&company=ABC Products

An XML response is returned. If successful the response should look like
<MGRESPONSE><OK>Update Ok</OK></MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors



DMMAddLeads Action:

The API Add Leads Action is a batch version of the DMMAddLead Action with the batch data provided in an XML format. For additional information see the dmmaddlead method. If you use AddLeads, you will need to make the CSV name have some sort of variable like a date stamp, or it will overwrite exisiting lists with the same file name. Example name the file: CompanyName_031213_1210.csv

A customer email address is required as an input field. This is the customer's email address on the account not the lead's email address

  • customeremail

The following are field names that will be accepted by the API when adding a lead

  • data

data should be XML formatted as follows:

<LEADS>
  <LEAD>
    <ListName>Your List Name</ListName>
    <Name>John Doe</Name>
    <Company>Your Company</Company>
    <Address1>123 Fake St</Address1>
    <Address2>Apt 45</Address2>
    <City>Springfield</City>
    <State>IL</State>
    <Zip>98765</Zip>
    <Phone>123-456-7890</Phone>
  </LEAD>
  <LEAD>
  ...
  </LEAD>
  ...
</LEADS>
An XML response is returned. If successful the response should look like
<MGRESPONSE><OK>Update Ok</OK></MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors Multiple errors may be returned and errors specific to a lead will have a lead # of which position the lead with the error was in the batch data.



GetDMMFunds Action:

The API Get Account Balance returns the balance on a customers campaign account.

A customer email address is required as an input field and XML with a BALANCE is returned

  • customeremail
Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&action=getdmmfunds&customeremail=yourcustomer@yoursite.com

An XML response is returned. If successful the response should look like
<MGRESPONSE><BALANCE>100.00</BALANCE></MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors



GetDMMCampaigns Action:

The API Get DMM Campaigns returns campaign details for all campaigns for a customers account Includes shipments and card information.

A customer email address is required as an input field and XML with a BALANCE is returned

  • customeremail
Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://directmailmanager.com/api/mgapi.asp?apikey=12345&idcust=12345&action=getdmmcampaigns&customeremail=yourcustomer@yoursite.com

An XML response is returned. If successful the response should look like
<MGRESPONSE> 
  <DMMCAMPAIGN>
    <ORDERNO>66610</ORDERNO>
    <CAMPAIGNNAME>Test Campaign</CAMPAIGNNAME>
    <JPGFRONT>
    http://postcardservices.com/designerNEW/userdata/2025/thumbs/3031640001.jpg
    </JPGFRONT>
    <JPGBACK>
    http://postcardservices.com/designerNEW/userdata/2025/thumbs/3031640002.jpg
    </JPGBACK>
    <PDF>
    http://postcardservices.com/designerNEW/userdata/2025/pdf/303164.pdf
    </PDF>
    <SIZE>4.13 x 5.97</SIZE>
    <SHIPMENTS>
      <SHIPMENT>
        <DATE>11/22/2011 4:12:14 PM</DATE>
        <CARDCOUNT>2</CARDCOUNT>
        <LISTNAME>test2.csv</LISTNAME>
        <PRICE>0.92</PRICE>
      </SHIPMENT>
      <SHIPMENT>
        <DATE>11/22/2011 4:12:24 PM</DATE>
        <CARDCOUNT>3</CARDCOUNT>
        <LISTNAME>test.csv</LISTNAME>
        <PRICE>1.38</PRICE>
      </SHIPMENT>
    </SHIPMENTS>
  </DMMCAMPAIGN>
  <DMMCAMPAIGN>
  .
  .
  .
  </DMMCAMPAIGN>
</MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors

AttachImage Action:

The API Attach Image uploads and image and attaches it to an order or campaign.

A customer email address, an order #, and a filename are required as an input fields and XML with a OK and the name of the File we saved it as are returned

  • customeremail
  • orderno
  • filename
Data should use the HTML post method to submit the API with the file attached with standard multipart form-data encoding. sample post to the API would look like:

An XML response is returned. If successful the response should look like

<MGRESPONSE> <OK>File Attached to Order</OK> <FILENAME>Name we saved the file as</FILENAME> </MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>

For a complete list of error codes and descriptions, see Errors

DMMMailList Action:

The API DMM Mail List triggers for mailing an existing list to an existing campaign.

A customer email address, an order #, and a listname are required as an input fields and XML with a OK and number of pieces to be mailed are returned. If there are insufficient funds in the account or the order # or listname are invalid an error message will be returned

  • customeremail
  • orderno
  • listname
Data should use the HTML post method to submit the API with the file attached with standard multipart form-data encoding. sample post to the API would look like:
The Status returned will include the following options. This list is not necessarily complete and subject to change:

  • Campaign Order is Invalid - Please Contact Customer Serivce if you see this
  • Not enough funds are available in your balance for this list
  • List has already been added to campaign
  • Your campaign has been mailed to your list.

An XML response is returned. If the order # and list are valid the response should look like

<MGRESPONSE> <STATUS>Text Indicating Sucess of Mailing</STATUS> </MGRESPONSE>

Failure will produce an error like

<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>

For a complete list of error codes and descriptions, see Errors

DMMAddLeadAndMail Action:

This is a combination of the dmmaddlead action and the dmmmaillist action. Requires the orderno from the dmmmaillist and all of the input values from addlead. For more information see the DMMMailList and DMMAddLead actions.



DMMAddLeadsAndMail Action:

This is a combination of the dmmaddlead action and the dmmmaillist action. Requires the orderno from the dmmmaillist and all of the input values from addleads. For more information see the DMMMailList and DMMAddLeads actions.



SetLowBalanceWarningAmt Action:

Sets the Low Balance Warning Amount Level. When orders are placed and the account balance is below this level, a low balance warning amount email is sent to the customer.

A customer email address and amount are required as an input fields and XML with a OK indicator or error is returned.

  • customeremail
  • amount


Error Codes and Descriptions

The Following error codes may be found when working with the API

  • 1 - "Invalid Request Type (POST is Required)"
  • 2 - "Invalid API Key"
  • 3 - "Invalid API User ID"
  • 4 - "Invalid User Credentials"
  • 5 - "Action Not Specified"
  • 6 - "Requested Customer Invalid"
  • 7 - "Customer Already Exists"
  • 8 - "New Password not specified"
  • 9 - "New Email not specified"
  • 10 - "Invalid XML Format"
  • 11 - "Order Not Active"
  • 12 - "Order No or File Name must be provided"
  • 13 - "File Name Provided Already Exists and was not created by the API"
  • 14 - "Order No and File Name can not both be provided"
  • 15 - "Invalid Order No"
  • 16 - "Only files of type (valid file types) are allowed"
  • 17 - "File Not Found" - The list was not found in the specified customers account
  • 20 - "Invalid Amount" - The amount specified was invalid or blank
  • 111 - "Lead # - Order Not Active"
  • 112 - "Lead # - Order No or File Name must be provided"
  • 113 - "Lead # - File Name Provided Already Exists and was not created by the API"
  • 114 - "Lead # - Order No and File Name can not both be provided"

 

How to get the API:

The API is free of charge. An API Access Key is generated when you create your account at Direct Mail Manager. It is that easy!

 

Links