• Let’s start off with the very basics. The base URL for all our API methods is https://api.maropost.com/accounts/:accountID/ where: accountID is your assigned account ID;  you’ll see it in your browser’s URL search field when you log in to your Maropost application.  After that, you will complete the full path of the URL depending on the API method you intend to use.   You’ll find the online API guide on the Connections page (mouse over your username and then select “Connections” from the drop-down menu).
  • You’ll also need to pass in an authentication token as a query string parameter with your API method calls.  Your account administrator will create one for you in the Connections page within the application.  If you have any 3rd parties that are integrating their systems into Maropost on your behalf, it’s best to create their own authentication token with just enough privileges to get the job done.  This restriction is a good security measure to protect your most valuable asset:  your contacts’ email addresses.
  • Our RESTful API supports both XML and JSON-formatted data payloads.  To specify which option your system prefers using, you’ll need to set two headers in your HTTPS method calls.  If you prefer JSON, then set content-type: application/json and accept: application/json.  Or, if you prefer XML, then set content-type: application/xml and accept: application/xml.  We’ve actually made it easy for you so that you don’t have to designate the headers if you don’t want to.  All you need to do is append either .json or .xml to your API method call.  We’ll take care of the rest!
  • If you are using our API to fetch data from the Maropost platform, you should have some idea of how much data you will be pulling with each method call.  Remember that data transfers are all being done over HTTPS which has an inherent timeout. Data sockets over HTTPS don’t stay open indefinitely. Using our API to fetch hundreds of thousands of records is improper usage. If you want to be pulling large amounts of data, then Data Workflows for automated data extracts is the proper way to go.
  • To keep the payload of data returned in any given GET call to a manageable size, Maropost Marketing Cloud returns data-sets in “pages” of 200 records.  The response payload will include the number of total pages that are included in the full result set.  Use the page=N  query string parameter to retrieve each “page” of data until you’ve retrieved the full result set.
  • The most common system-to-system integration actions are to subscribe new contacts to a list and to provide updated contact information. Fortunately, both actions are encapsulated in the same API method.  POST /lists/:listID/contacts is our API method that lets you both create a new contact record and update an existing one. True, by definition of REST, a POST command is reserved for creating new resources while a PUT command is reserved for updating an existing resource.   But designing this API method to act as an “upsert” method allows you to host your own contact profile page and easily send both new contacts and updated contacts to Maropost.
  • You can still use PUT /lists/:listID/contacts/:id to update a contact record, wherein: id is the contact’s own Maropost internal ID.  In fact, this API method is the only one that allows you to change a contact’s email address.  To update a contact’s email address via this method, you’ll first need to find out the contact’s internal Maropost contact ID by using the GET /contacts/email?contact[email]=api@email.com method call.
  • One final note.  As you are starting out building your integration, we recommend that you download and install Postman (https://www.getpostman.com) on your computer.  This desktop application allows you to quickly and easily test out your API method calls that you’ll ultimately be making programmatically.  It’s the best way to check your syntax and to view what the response payloads look like.