Enthusem Developer API - Recently Updated Pages

mailer.add

enthhusembrad — Thu, 01 Apr 2010 16:43:41 CDT

Schedules a mailer to be mailed

Authentication

This method requires an authentication token.

Post Parameters

contact_id (Required)
The id of the contact to mail.
design_id (Required)
The id of the design to mail.
message (Required)
The message printed on the inside of the mailer.
mail_date (Required)
The date the mailer is to mail.
font (Required)
The font the message will be printed in { Verdana, Steve, Eminenz, Dreamer }
format (Required)
The format and size of the printed mailer. See formats below.

message_id (Optional)
The id of the message template used.
attachment_id (Optional)

The id of the attachment to use.

Response Format

<mailer_id>{mailer_id}</mailer_id>
<mailer_no>574332</mailer_no>

<pickup_code>ABC123</pickup_code>

</mailer>

Formats

0 - 5.5 x 8.5 folded note card w/ clear coat
1 - 4 x 6 note card (Pending)
2 - 4 x 6 note card w/ clear coat (Pending)
3 - 5.5 x 8.5 w/ clear coat (Pending)
4 - 8.5 x 11 letter (Pending)

Error Codes

100 - invalid token
101 - token expired
105 - insufficient credits
106 - user must update return address
107 - message too long (max 1024 characters).
500 - server error

contact.update

enthhusembrad — Thu, 01 Apr 2010 16:04:31 CDT

Updates a contact.

Authentication

This method requires an authentication token.

Post Parameters

contact_id (Required)
The id of the contact to update.
first_name (Required)

The contact's first name.
last_name (Required)

The contact's last name.
address1 (Required)
The contact's address.
city (Required)

The contact's city.
state_province (Required)

The state or province of the contact's address.
zip_postal (Required)

The zip or postal code of the contact's address.
postal_verified (Required)

Whether the contact's address has been postal verified. See contact.validateAddress.

address2 (Optional)

The contact's address part 2.
country (Optional)

The contact's country. Must be a valid 2-character country code. Default: US
organization (Optional)

The contact's organization.
title (Optional)

The contact's job title.
phone (Optional)

The contact's phone number.
email (Optional)

The contact's e-mail address.

Sample Response

No response body returned on a successful request. Only HTTP 200 OK status code.

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

contact.add

enthhusembrad — Wed, 11 Nov 2009 16:01:11 CST

creates a contact/recipient and returns a contact_id

Authentication

This method requires an authentication token.

Post Parameters

first_name (Required)

The contact's first name.
last_name (Required)

The contact's last name.
address1 (Required)
The contact's address.
city (Required)

The city of the contact.
state_province (Required)

The state or province of the contact's address.
zip_postal (Required)

The zip or postal code of the contact's address.
postal_verified (Required)

Whether the contact's address has been postal verified. See contact.validateAddress.

address2 (Optional)

The contact's address continued.
country (Optional)
The contact's country. Note: must be the 2 letter country code.
organization (Optional)

The contact's organization.
title (Optional)

The contact's job title.
phone (Optional)

The contact's phone number.
email (Optional)

The contact's e-mail address.

Sample Response

<row_num>1</row_num>
<contact_id>c7b1ca25-bd7a-4882-a830-6d430ae81ed3</contact_id>
<first_name><![CDATA[Test]]></first_name>
<last_name><![CDATA[Contact]]></last_name>
<company><![CDATA[]]></company>
<address1><![CDATA[13043 W LINEBAUGH AVE]]></address1>
<address2><![CDATA[]]></address2>
<city><![CDATA[TAMPA]]></city>
<state_province><![CDATA[FL]]></state_province>
<zip_postal><![CDATA[33626]]></zip_postal>
<country><![CDATA[US]]></country>
<last_mail_date />
<pickup_count>1</pickup_count>

</contact>

Error Codes

101 - Token expired
103 - Required parameters not posted
106 - Contact exists
500 - Server error

user.recoverPassword

enthhusembrad — Wed, 11 Nov 2009 15:03:02 CST

Sends the user's password to the e-mail on file.

Authentication

This method does not require an authentication token.

Post Parameters

email (Required)

E-mail of the user.

Sample Response

No response body returned on a successful request. Only HTTP 200 OK status code.

Error Codes

105 - E-mail not found.
106 - Error sending mail.
500 - Server error

Authentication

enthhusembrad — Tue, 10 Nov 2009 16:22:50 CST

An authentication token is a required to call most methods. To get an authentication token you need to call the user.getToken method. The table below shows the parameter you'll need to POST and the format of a successful response. Each user is associated with one or more accounts and each user has a default account. You pass just the username and password to get a token for the user's default account or you can optionally pass a valid account_id to get a token that is associated with an account other than the user's default account. To get the account_id for accounts the user has access to you can call the user.getAccounts method.

Method	Parameters	Results
user.getToken	email, password, remember [optional account_id]	<token> <token_id>{token}</token_id> </token>

contact.get

enthhusembrad — Fri, 06 Nov 2009 11:41:19 CST

Gets a user.

Authentication

This method requires an authentication token.

Post Parameters

contact_id (Required)
ID of the contact.

Sample Response

<row_num>1</row_num>
<contact_id>c7b1ca25-bd7a-4882-a830-6d430ae81ed3</contact_id>
<first_name><![CDATA[Test]]></first_name>
<last_name><![CDATA[Contact]]></last_name>
<company><![CDATA[]]></company>
<address1><![CDATA[13043 W LINEBAUGH AVE]]></address1>
<address2><![CDATA[]]></address2>
<city><![CDATA[TAMPA]]></city>
<state_province><![CDATA[FL]]></state_province>
<zip_postal><![CDATA[33626]]></zip_postal>
<country><![CDATA[US]]></country>
<last_mail_date />
<pickup_count>1</pickup_count>
<external_id></external_id>

</contact>

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

mailer.preview

enthhusembrad — Tue, 27 Oct 2009 09:36:48 CDT

Returns a PDF preview of what the mailer will look like.

Authentication

This method requires an authentication token.

Post Parameters

first_name (Required)

The recipient's first name.
last_name (Required)

The recipient's last name.
address1 (Required)
The recipient's street address.
city (Required)

The recipient's city.
state_province (Required)

The recipient's state/province.
zip_postal (Required)

The recipient's zip/postal code.
message (Required)

The message body.
font (Required)

The font of the message.
design_id (Required)

The id of the design for the front of the card.

address2 (Optional)

The recipient's street address.
organization (Optional)

The recipient's organization.
country (Optional)

The recipient's country.

Sample Response

<rsp>

<param></param>
<param></param>

</rsp>

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

user.getToken

enthhusembrad — Thu, 22 Oct 2009 14:54:46 CDT

Used to get an authentication token

Authentication

This method does not require an authentication token.

Post Parameters

email (Required)
The user's email address. See user.getToken.
password (Required)
User's password.
remember (Required)
Creates a token that does not expire.

account_id (Optional)

The account to log in to. Otherwise logs into the first account created.

Response Format

<token>

<token_id>fe502fcd-65b4-4871-93a6-00c127368283</token>

</token>

Error Codes

103 - Required parameters not posted
104 - Invalid username and password combination
105 - Invalid account_id
500 - Server error

Example Usage

curl --form-string "username=example@enthusem.com;password=aBadway2go;remember=false https://api.enthusem.com/services/xml/?method=user.getToken&apikey=9219142d-f080-4a8b-ae38-7e139bad47a3

user.getDesigns

enthhusembrad — Thu, 13 Aug 2009 16:35:03 CDT

Gets a user's designs

Authentication

This method requires an authentication token.

Post Parameters

No post parameters required.

Sample Response

<design>

<design_id>47672762-e7ef-45f0-9bff-0310afddb232</design_id>
<design_no>123456</design_no>
<credit_cost>3</credit_cost>
<is_shared>false</is_shared>
</design>

</designs>

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

design.share

enthhusembrad — Tue, 11 Aug 2009 09:12:10 CDT

Shares a design with all users in the account.

Authentication

This method requires an authentication token and membership in the ADMIN role.

Post Parameters

design_id (Required)

The display name of the account.
shared (Required)
{ True | False } Whether the design should be shared or not.

Sample Response

No response body returned on a successful request. Only HTTP 200 OK status code.

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

account.update

enthhusembrad — Tue, 11 Aug 2009 09:10:01 CDT

Updates account information.

Authentication

This method requires an authentication token and membership in the ADMIN role.

Post Parameters

account_name (Required)

The display name of the account.
pickup_url (Required)

The url of the page where recipients enter pickup codes. Uses default if blank.

Sample Response

No response body returned on a successful request. Only HTTP 200 OK status code.

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

user.getStatistics

enthhusembrad — Fri, 07 Aug 2009 10:38:43 CDT

Gets user statistics

Authentication

This method requires an authentication token.

Post Parameters

No post parameters required.

Sample Response

<mailers_sent>5000</mailers_sent>
<total_pickups>3000</total_pickups>

<unique_pickups>2500</unique_pickups>
<response_rate>16.35%</response_rate>

</statistics>

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

user.signup

enthhusembrad — Fri, 31 Jul 2009 16:16:05 CDT

Creates a new user and associated account

Authentication

This method does not require an authentication token.

Post Parameters

email (Required)

User's email
password (Required)

The street part of the user's address.
full_name (Required)

User's full name.

account_name (Optional)
The name of the account. Defaults to organization or lastly full_name.
organization (Optional)
The user's organization.

address1 (Optional)
The street part of the user's address.

address2 (Optional)
The street part of the user's address continued.
city (Optional)

The city of the user's address.
state_province (Optional)

The state or province of the user's address.

zip_postal (Optional)

The zip or postal code of the user's address.
affiliate_id (Optional)

The id of the affiliate.

Note: If address1 is passed, city, state_province and zip_postal are also required. If these params are not passed, the user will not be able to send mail until user.update has been called to update their return address.

Sample Response

<user>

<user_id>f69a7060-ec86-4b1c-b756-5e28815caf67</user_id>

<full_name />

<address1 />

<address2 />

<city />

<state_province />

<zip_postal />

<country />

<date_created>2009-06-25T14:09:00</date_created>

<email>brad+webtest2@enthusem.com</email>

<must_update>true</must_update>

<roles>OWNER, ADMIN, USER</roles>

<is_enabled>true</is_enabled>
<credits>0</credits>

</user>

Error Codes

104 - email exists
500 - server error

Introduction

enthhusembrad — Thu, 30 Jul 2009 11:10:01 CDT

The primary goal of the Enthusem API is simplicity. In fact, to use this API all you need to know is how to create an HTTP form POST and how to parse an XML response.

Getting Started

For starters, you'll always be submitting a SSL secured HTTP POST to a URI in the following format:

https://api.enthusem.com/services/xml/?method={method}&apikey={apikey}&token_id={token_id}

The {method} variable is the name of the method you want to call and the {apikey} is a unique value you get when you signup for an enthusem.com developer account. The {apikey} value stays constant unless you request a new apikey for your developer account.

Since every request you make is an HTTP POST you'll need to know what parameters are expected for each method. Every method is going to return an XML response that will either be the results from a successful method call or the XML returned will indicate an error and provide an error code and message (see Error Response Format below).

Most methods will require you to pass a "token" value in the query string. The token value is a simple authentication key that you request before each session by calling the user.getToken method.

design.add

enthhusembrad — Tue, 21 Jul 2009 09:24:30 CDT

Uploads a design and adds it to the user's designs.

Authentication

This method requires an authentication token.

Post Parameters

shared (Required) {true | false}
Allows design to be used by all users under the account.
Requires membership in the ADMIN role if true.
{file-data} (Required)

multipart/form-data. The actual file being uploaded.

Sample Responses

Properly sized image (1710px x 1304px)

<design>

<design_id>47672762-e7ef-45f0-9bff-0310afddb232</design_id>
<credit_cost>3</credit_cost>

</design>

Improperly sized image (Must be .jpg or .png)

<image>

<image_url>https://secure.enthusm.com/services/croptemp/47672762-e7ef-45f0-9bff-0310afddb232.jpg</image_url>
<image_id>47672762-e7ef-45f0-9bff-0310afddb232</image_id>

</image>

Notes: Pass image_id into design.crop to add the image.

Error Codes

101 - Token expired
103 - Required parameters not posted
104 - File too large
105 - More than one file uploaded
106 - No files upload
107 - Image does not meet required specifications
500 - Server error

Enthusem Developer API Home

enthhusembrad — Mon, 20 Jul 2009 09:42:28 CDT

Welcome to the enthusem API documentation site. Here you'll find information for software developers and the most recent documentation on the enthusem.com api(s).

Our goal is to eventually expose three API interfaces which will include a simple XML API (xml-rpc like), REST and SOAP. Initially, we're rolling out with what we're calling the Enthusem Simple API because as the name implies, it's the simplest.

The documentation on this site is a work in progress but please don't be shy about posting feedback, questions or suggestions.

Documentation

user.getMailers

enthhusembrad — Tue, 14 Jul 2009 16:43:43 CDT

Gets a list of mailers sent by the user.

Authentication

This method requires an authentication token.

Post Parameters

user_id (Optional)

The id of a different user in the account.

Sample Response

<mailers>
<mailer_id>b55ea3b2-e3b7-40b0-8fbf-01000f61ea7a</mailer_id>
<mailer_no>115158</mailer_no>
<date_created>2009-07-09T17:43:06.733Z</date_created>
<maildate>2009-07-11T04:00:00Z</maildate>
<mailer_status>PROCESSING</mailer_status>
<credits_used>3</credits_used>
<message>This is a web test from Brad.</message>
<design_id>d60efabf-5e63-41af-ae4d-003bf9b2adfe</design_id>
<attachment_id />
<attachment_description />
<recipient_name>Test Contact2</recipient_name>
<recipient_company />
<recipient_address1>13043 W LINEBAUGH AVE</recipient_address1>
<recipient_address2 />
<recipient_city>TAMPA</recipient_city>
<recipient_state_province>FL</recipient_state_province>
<recipient_zip_postal>33626</recipient_zip_postal>
<return_name>Web test update</return_name>
<return_address1>13043 W LINEBAUGH AVE</return_address1>
<return_address2 />
<returncity>TAMPA</returncity>
<return_state_province>FL</return_state_province>
<return_zip_postal>33626</return_zip_postal>
</mailers>

Error Codes

101 - Token expired
103 - Required parameters not posted
500 - Server error

account.updateUser

enthhusembrad — Fri, 10 Jul 2009 15:40:34 CDT

Updates a user associated with an account

Authentication

This method requires an authentication token and membership in the ADMIN role.

Post Parameters

user_id (Required)

The id of the user to update.

roles (Required)

The permissions the user has under the account. (OWNER, ADMIN, USER)

Response Format

No response body returned on a successful request. Only HTTP 200 OK status code.

Error Codes

100 - invalid token
101 - invalid permission to update user
102 - invalid user_id
103 - invalid account_id
104 - invalid roles
500 - server error

account.getUsers

enthhusembrad — Fri, 10 Jul 2009 15:39:57 CDT

Gets a list of users for an account

Authentication

This method requires an authentication token and membership in the ADMIN role.

Post Parameters

No post parameters required.

Sample Response

<users>

<user>

<user_id>f69a7060-ec86-4b1c-b756-5e28815caf67</user_id>

<full_name />

<address1 />

<address2 />

<city />

<state_province />

<zip_postal />

<country />

<date_created>2009-06-25T14:09:00</date_created>

<email>brad+webtest2@enthusem.com</email>

<must_update>true</must_update>

<roles>USER</roles>

<is_enabled>true</is_enabled>
<credits>0</credits>
</user>
<user>

<user_id>f69a7060-ec86-4b1c-b756-5e28815caf67</user_id>

<full_name />

<address1 />

<address2 />

<city />

<state_province />

<zip_postal />

<country />

<date_created>2009-06-25T14:09:00</date_created>

<email>brad+webtest2@enthusem.com</email>

<must_update>true</must_update>

<roles>USER</roles>

<is_enabled>true</is_enabled>
<credits>0</credits>
</user>

</users>

Error Codes

100 - invalid token
101 - invalid account_user_id
500 - server error

account.get

enthhusembrad — Fri, 10 Jul 2009 15:39:42 CDT

Gets details for the account associated with the current authentication token.

Authentication

This method requires an authentication token.

Post Parameters

No post parameters required.

Response Format

<account>
<account_id>a4b158bb-6a9a-48e2-a7d1-d28a3eb04c70</account_id>
<account_name>Testing</account_name>
<date_created>2009-05-21T20:11:00Z</date_created>
<mailer_credits>0</mailer_credits>
<package>0</package>
<organization>Testing</organization>
<disk_quota>10</disk_quota>
<pickup_url />
<credit_price />
<allow_custom_pickup>false</allow_custom_pickup>
</account>

Error Codes

101 - Token expired
103 - Required parameters not posted
109 - Admin access required
500 - server error