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 Private Label (M3) Web-To-Print-Mail Stores, Postcard Services, Direct Mail Manager On-Demand Direct Mail 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.
- 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
Valid Postcard Services API Action Values
- listcustomers - Takes no arguments and returns all customer information for a private store setup.
- listcustomer - Requires customeremail and returns all customer information for a customer with the email specified.
- getallcampaigns - requires customeremail value and returns all Postcard Services orders for the customer specified.
- 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 card artwork for a customer. Requires customeremail.
Valid 2ndShot API Action Values
- addlead - Create a new list or overwrite an existing list to be processed for 2ndShot Campaigns.
- addleads - Creates or overwrites existing lists with multiple leads to be processed for 2ndShot Campaigns.
- addcustomleads - Append multiple leads to a current list to be processed or to create a new list to be processed for 2ndShot Campaigns with as many custom fields as required.
- attachimage - Attaches an Image to an 2ndShot Campaign.
- createorder - Create a Saved Order which can be retrieved and completed by a customer after logging in.
Valid Direct Mail Manager API Action Values
- getdmmfunds - Returns the Direct Mail Manager Account Balance for a Customer.
- getdmmcampaigns - Returns the Direct Mail Manager Campaigns for a Customer.
- dmmaddlead - Create a new list or Overwrite an existing list to be processed in Direct Mail Manager.
- dmmaddleads - Create a new list or Overwrite existing lists to be processed in Direct Mail Manager.
- dmmmaillist - Directs DMM to mail a list to an order.
ListCustomers Action:
The API List Customers Action lists all customer records related to your account.
There are no additional input parameters required for this action
Data should use the HTML post method to submit the API. A sample post to the API would look like: http://postcardservices.com/api/mgapi.asp?apikey=12345&idcust=12345&action=listcustomers
An XML response is returned. If successful the response should look like the following, however it will contain all of the customer fields.
<MGRESPONSE>
<CUSTOMER>
<EMAIL> youremail@yoursite.com </EMAIL>
<FIRSTNAMENAME> Customer Name </FIRSTNAME>
</CUSTOMER>
<CUSTOMER>
<EMAIL> youremail2@yoursite.com </EMAIL>
<FIRSTNAME> Another Customer Name </FIRSTNAME>
</CUSTOMER>
</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
ListCustomer Action:
The API List Customer action lists the account details for a specific customer.
The following field is required by the API when requesting a single customer record
- customeremail
Data should use the HTML post method to submit the API. A sample post to the API would look like: http://postcardservices.com/api/mgapi.asp?apikey=12345&idcust=12345&action=listcustomer&customeremail=yourcustomer@yoursite.com
An XML response is returned. If successful the response should look like the following, however it will contain all of the customer fields.
<MGRESPONSE> <CUSTOMER> <EMAIL> youremail@yoursite.com </EMAIL> <FIRSTNAME> Customer Name </FIRSTNAME> </CUSTOMER> </MGRESPONSE>
Failure will produce an error like
<MGRESPONSE><ERROR><CODE>errorcode</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors
GetAllCampaigns (or Orders) Action:
The API GetAllCampaigns action lists the order details for a specific customer.
The following field is required by the API
- customeremail
Data should use the HTML post method to submit the API. A sample post to the API would look like:
curl http://postcardservices.com/api/mgapi.asp -d apikey=12345 -d idcust=12345 -d action=getallcampaigns -d "customeremail=yourcustomer@yoursite.com"
An XML response is returned. If successful the response should look like the following, however it will contain all of the customer fields.
<MGRESPONSE> <CUSTOMER> <EMAIL> youremail@yoursite.com </EMAIL> <FIRSTNAME> Customer Name </FIRSTNAME> </CUSTOMER> </MGRESPONSE>
Failure will produce an error like
<MGRESPONSE><ERROR><CODE>errorcode</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>
For a complete list of error codes and descriptions, see Errors
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://postcardservices.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>errorcode</CODE>
<DESCRIPTION>error description</DESCRIPTION>
</MGRESPONSE>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://postcardservices.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>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://postcardservices.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>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://postcardservices.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>AddLead 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.
Either OrderNo or ListName should be used, not both. If creating a list on the customers account, a list name should be used. If creating for an existing order on the second shot mailing, an existing orderNo should be used. An error will be returned is the Order No is not an active campaign for the customer.
The following are field names that will be accepted by the API when adding a lead
- OrderNo
- ListName
- name
- company
- address1
- address2
- city
- state
- zip
Data should use the HTML post method to submit the API. A sample post to the API would look like:
http://postcardservices.com/api/mgapi.asp?apikey=12345&idcust=12345&action=addlead&orderno=123&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>AddLeads Action:
The API Add Leads Action is a batch version of the AddLead Action with the batch data provided in an XML format. For additional information see the addlead method.
http://postcardservices.com/api/mgapi.asp?apikey=12345&idcust=12345&action=addlead&orderno=123&data=<LEADS></LEAD>...</LEAD></LEADS>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>
<OrderNo>Your Order #</OrderNo>
<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>
</LEAD>
<LEAD>
...
</LEAD>
...
</LEADS>
<MGRESPONSE>
<OK>Update Ok</OK>
</MGRESPONSE>Failure will produce an error like
<MGRESPONSE>
<ERROR><CODE>error code</CODE>
<DESCRIPTION>error description</DESCRIPTION>
</MGRESPONSE>AddCustomLeads Action:
The API Add Custom Leads Action is a batch version of the AddLead Action with the batch data provided in an XML format. It also allows for as many custom Varaible data columns as needed, but is for 2ndShot Campaigns only. For additional information see the addlead method.
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>
<OrderNo>Your Order #</OrderNo>
<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>
<AnyCustomField1>YourCustomInfo1/AnyCustomField1>
<AnyCustomField2>YourCustomInfo2</AnyCustomField2>
<AnyCustomField3>YourCustomInfo3</AnyCustomField3>
</LEAD>
<LEAD>
...
</LEAD>
...
</LEADS>
Example Usage Using Curl:
curl https://postcardservices.com/api/mgapi.asp -d apikey=yourapikey -d idcust=your_customer_id -d "customeremail=you@yourcompany.com" -d "action=addcustomleads" -d "data=<LEADS><LEAD><ORDERNO>Your Order No<ORDERNO><LISTNAME>TestListName.csv<LISTNAME><NAME>Test Name<NAME><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>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
http://postcardservices.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>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
http://postcardservices.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>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
http://postcardservices.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>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 new list to be 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
- orderID
- 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://postcardservices.com/api/mgapi.asp?apikey=12345&idcust=12345&orderid=123&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>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>
<MGRESPONSE><OK>Update Ok</OK></MGRESPONSE>Failure will produce an error like
<MGRESPONSE><ERROR><CODE>error code</CODE><DESCRIPTION>error description</DESCRIPTION></MGRESPONSE>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
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>
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
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>Create Order Action:
Creates a Saved Order with the customer can load after logging into the application.
The CreateOrder action takes a data input with formatted XML which specifies all of the data required for the order. Optionally, files may be attached to the order lines. The filename and input fieldname are specified under the files section of the order
- data - XML formatted as below
- filename1 - This fieldname is specified by you in the files section
- filename2 - This fieldname is specified by you in the files section
data should be XML formatted as follows:
<ORDER>
<EMAIL>yourcustomer@yoursite.com</EMAIL>
<PRODUCTS>
<PRODUCT>
<QTY>1</QTY>
<SKU>OUR SKU</SKU>
<FILES>
<FILE>
<FIELDNAME>The File is attached to the request</FIELDNAME>
</FILE>
<FILE>
...
</FILE>
</FILES>
</PRODUCT>
<PRODUCT>
...
</PRODUCT>
</PRODUCTS>
...
</ORDER>
<MGRESPONSE>
<OK>Order Created Successfully</OK>
<ORDERNO>123456</ORDERNO>
<TOTAL>150.00</TOTAL>
</MGRESPONSE>
Failure will produce an error like
<MGRESPONSE>
<ERROR><CODE>error code</CODE>
<DESCRIPTION>error description</DESCRIPTION>
</MGRESPONSE>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"
- 18 - "File Name Provided Already Exists and the fields provided do not match the existing file"
- 19 - "Product Not Found"
- 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!
