API Documentation

MailBuild

API documentation > Posting a SOAP envelope

How to POST some SOAP

Not all development environments and languages offer a simple way to consume web services. However, most offer the ability to make a POST request to an address. If you can do that, then you can make use of the MailBuild API.

Language specifics

The first thing you're going to have to find is the code to make a simple POST request with a payload, and handle the ensuing response in your language of choice. Whether it be .NET, Java, PHP, Ruby or otherwise, there are many resources out there to help you get over this initial task. Once you've got your code for posting a request working, you're ready to move on to the specifics of working with the MailBuild API.

The important bits

There are a couple of small additions you'll need to make to your post request so it behaves just like a SOAP request. The first thing to change is the URL you will be posting to. Below is the URL you will need to call, where yoursitename is the MailBuild site address you specified when signing up:

http://yoursitename.createsend.com/api/api.asmx

Next, change the Content-Type header in your code to reflect the following:

Content-Type: text/xml; charset=utf-8

In order for this post to actually call the API method, we need to add a header that is not normally part of a standard HTTP request, the SOAPAction header. Add this header in the following form, making sure the inverted commas (") are included.

SOAPAction: "http://api.createsend.com/api/Subscriber.Add"

Last but not least, stream the actual SOAP packet into the request stream. Below is an example SOAP packet for adding a subscriber. The format of these packets for our other methods is available in their individual documentation pages. Don't forget to UTF-8 encode the content in the request stream.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Subscriber.Add xmlns="http://api.createsend.com/api/">
      <ApiKey>string</ApiKey>
      <ListID>int</ListID>
      <Email>string</Email>
      <Name>string</Name>
    </Subscriber.Add>
  </soap:Body>
</soap:Envelope>

Following is an example response you will receive back. Again, the exact responses you can expect from each method are available on their documentation pages for that specific method.

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Subscriber.AddResponse xmlns="http://api.createsend.com/api/">
      <Subscriber.AddResult>
        <Code>int</Code>
        <Message>string</Message>
      </Subscriber.AddResult>
    </Subscriber.AddResponse>
  </soap:Body>
</soap:Envelope>