webservices

Managing Images

by Administrator on ‎03-25-2011 10:07 AM

At the moment, we do not support images in "My Stock Images" folder. 

 

For all image related APIs, you must specify "accept" header in your API call in addition to "content-type" header that is required for other APIs.  Both headers now must be passed in as part of the request and their values must be set to application/atom+xml.

 

Unsupported Methods

  • Update Details of an Image - To change the image name or image itself, you need to delete an existing image and upload again
  • Get Details of a Folder
  • Rename a Folder
  • Delete a Folder

Obtaining a List of Folders

 

In your Constant Contact account, all images are stored in a folder.  If you do not subscribe to MyLibrary+, you only see images without any folders since you are limited to only 5 images, but they are still represented to be in a folder.  Therefore, to access or upload any images, you must specify folder location in the URI regardless of whether you subscribe to MyLibrary+.  Please note that "My Stock Images" folder will not be returned as we currently do not support it.

 

To get a list of image folders, you need to call GET method on the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/library/folders

You should get a list of folders that exist for images in the account, as shown in below in the XML example.  Please make sure accept and content-type headers are set to application/atom+xml.  For details on the XML specification and parameters for image folders, please refer to Folder Collection and Resource Reference.

 

Please note that <Link><href> for each folder is returning a full URI starting with "http://api.constantcontact.com" while we only return a relative path, starting with "/ws/customers..." for a list of images.  The behavior for images is the correct one.  We will be addressing the issue with a folder's <href> in a future release and change it to a relative path.

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Image Folders</atom:title>
<atom:updated>2010-07-01T14:50:52.569-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders</atom:id>
<atom:entry>
<atom:title>Images</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/library/folders/1"/>
<atom:updated>2010-07-01T14:50:52.569-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/1</atom:id>
<atom:content>
<Folder id="tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/1">
<Name>Images</Name>
<Link>
<href>http://api.constantcontact.com/ws/customers/joesflowers/library/folders/1</href>
</link>
</Folder>
</atom:content>
</atom:entry>
<atom:entry>
<atom:title>Images</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/library/folders/2"/>
<atom:updated>2010-07-01T14:50:52.569-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2</atom:id>
<atom:content>
<Folder id="tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2">
<Name>Spring Images</Name>
<Link>
<href>http://api.constantcontact.com/ws/customers/joesflowers/library/folders/2</href>
</link>
</Folder>
</atom:content>
</atom:entry>
</atom:feed>

Creating a Folder

 

To create a new folder, you need to call the POST method on the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/library/folders

You need to specify in the XML body the name of the folder you want to create.  Use the following XML as the template:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
<atom:content>
<Folder>
<Name>Folder Name</Name>
</Folder>
</atom:content>
</atom:entry>

Obtaining a List of Images in a Folder

 

To get a list of images in a folder, you need to call the GET method on the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/library/folders/{folder-id}/images

You need to make sure you define accept header in your request and have its value set to application/atom+xml.

 

The result of the API call would return a list of images, each of which is included in <atom:entry>.  For details on the XML specification and parameters for images, please refer toImage Collection and Resource Reference.

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Images</atom:title>
<atom:updated>2010-07-15T17:59:15.208-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2/images</atom:id>
<atom:entry>
<atom:title>1278424356346.gif</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/library/folders/2/images/917"/>
<atom:updated>2010-07-06T09:51:38.649-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2/images/917</atom:id>
<atom:content>
<Image>
<FileName>1278424356346.gif</FileName>
<ImageURL>https://origin.ih.constantcontact.com/fs030/1100337304266/img/917.gif</ImageURL>
<Height>422</Height>
<Width>439</Width>
<Description>description</Description>
<Folder
id="tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2">
<Name>1278424351586</Name>
<Link>
<href>/ws/customers/joesflowers/library/folders/2</href>
</Link>
</Folder>
<MD5Hash>990ca0ed790e033668111c2b402b6b53</MD5Hash>
<FileSize>64712</FileSize>
<LastUpdated>2010-07-06T09:51:38.649-04:00</LastUpdated>
<Link>
<href>/ws/customers/joesflowers/library/folders/2/images/917</href>
</Link>
<FileType>GIF</FileType>
</Image>
</atom:content>
</atom:entry>
<atom:entry>
<atom:title>1278424356346.jpeg</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/library/folders/2/images/920"/>
<atom:updated>2010-07-06T09:51:41.156-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2/images/920</atom:id>
<atom:content>
<Image>
<FileName>1278424356346.jpeg</FileName>
<ImageURL>https://origin.ih.constantcontact.com/fs030/1100337304266/img/920.jpg</ImageURL>
<Height>422</Height>
<Width>439</Width>
<Description>description</Description>
<Folder id="tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/2">
<Name>1278424351586</Name>
<Link>
<href>/ws/customers/joesflowers/library/folders/2</href>
</Link>
</Folder>
<MD5Hash>ee988e4958b326b9151a062b4b17d57f</MD5Hash>
<FileSize>112315</FileSize>
<LastUpdated>2010-07-06T09:51:41.156-04:00</LastUpdated>
<Link>
<href>/ws/customers/joesflowers/library/folders/2/images/920</href>
</Link>
<FileType>JPG</FileType>
</Image>
</atom:content>
</atom:entry>
</atom:feed>

From the images collection, you can find out each image's type, dimensions and the folder to which it belongs.  The collection also returns each image's URL.  To get more detailed information about each image you need to obtain details of an image.

 

Uploading an Image

 

Uploading an image requires you to create a multipart/form-data request so you can pass not only the image itself but also the details of the image being uploaded, such as its name and type.  You need to call the POST method with a multipart/form-data request to the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/library/folders/{folder-id}/images

The first part of the request must contain the XML body about the image itself.  Its content-type header must be set to application/atom+xml.

 

Please note the following when you are forming your request:

 

  • The file name you pass in <FileName> element must have an extension.
  • The content-type header must match the type of file you are uploading regardless of the actual extension.
  • JPG and JPEG are synonymous and interchangeable.

The following is the minimum XML body you need:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
<atom:content>
<Image>
<FileName>1278008252289.gif</FileName>
<MD5Hash>990ca0ed790e033668111c2b402b6b53</MD5Hash>
<Description />
</Image>
</atom:content>
</atom:entry>

You can put your filename in <FileName> element.  Note that you need to generate MD5 hash value for your image and pass it in <MD5Hash> element.  This is to ensure that the image was uploaded correctly when the API is called.  We will use the hash value you passed with the hash value we generate on the image we received to make sure your image was uploaded correctly.  Finally, you can pass in a description for the image in <Description> element, but it is optional.

 

The second part of the request must be the binary stream of the image itself.  The second part's content type must be defined with the image type, such as image/jpg, image/gif or image/png.  You must set transfer-encoding for the second part to be binary so the image will be uploaded properly.

 

For all the details about how to manage your images and how our system handles your images, please refer to the Image Reference Guide.

 

Obtaining Details of an Image

 

To get details of an image that has already been uploaded, you need to call the GET method on the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/library/folders/{folder-id}/images/{image-id...

After you upload an image, our system will add additional attributes to the image so that even though you are only passing the image name, MD5 hash, image type and description.  For details on the XML specification and parameters for images, please refer to Image Collection and Resource Reference.

 

The returned XML would look like the following:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Bengal Tiger.JPG</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/library/folders/1/images/1"/>
<atom:updated>2010-04-20T16:10:10.713-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/library/folders/1/images/1</atom:id>
<atom:content>
<Image>
<FileName>Bengal Tiger.JPG</FileName>
<ImageURL>https://origin.ih.constantcontact.com/fs081/1100325770403/img/1.jpg</ImageURL>
<Height>257</Height>
<Width>226</Width>
<Description>tiger alt</Description>
<MD5Hash>401ba3a6f45834e0df0bba7d054c3c29</MD5Hash>
<FileSize>50362</FileSize>
<LastUpdated>2010-04-20T16:10:10.713-04:00</LastUpdated>
<ImageUsages>
<ImageUsage>
<Name>Attend Constant Contact Event</Name>
<Link>
<href>/ws/customers/joesflowers/campaigns/1100338276745</href>
<relationship>edit</relationship>
</Link>
</ImageUsage>
</ImageUsages>
<FileType>JPG</FileType>
</Image>
</atom:content>
</atom:entry>

There are several extra information that is now returned for an image.  The <ImageURL> element specifies a URL through which the image can be accessed.  The system also calculates width, height and file size of the image and put them in <Width>, <Height> and <FileSize> elements respectively.

 

Finally, the system keeps track of where images are used in our system and give you an information about all the email campaigns as well event invitations that use this image.  This information is available through <ImageUsages> element.  Each usage of the image will be passed through <ImageUsage> element, which will contain the reference to the email campaign or event invitation that is using the image.

 

Deleting an Image

 

To delete an image, you need to call the DELETE method on the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/library/folders/{folder-id}/images/{image-id...

{image-id} is the last numeric part of the <id> that is available with the image detail. 

 

Deleting All Images in a Folder

 

We also provide an ability to delete all images in a folder.  To do so, call the DELETE method on the images collection itself without specifying an image ID.

 

https://api.constantcontact.com/ws/customers/{username}/library/folders/{folder-id}/images