Sending with the API

Our API gives you access to all the endpoints you need to start sending programmatically. In this document we will cover off on some of those endpoints, specifically relating to templates, campaigns, and emails.

Key Concepts

There are 3 key pieces of our API that you will need to familiarize yourself with.

  • Finding and choosing a template.
  • Creating and updating a campaign.
  • Sending an email, either via one of our send integrations, or by receiving HTML as a response to be sent on your own pipes.

Each of these 3 items deals with one of the 3 key endpoints our API

  • /templates which deals with fetching all available templates, default JSON configuration and preview HTML.
  • /campaigns which lets you create, update or report aggregate stats on a campaign
  • /emails or /campaigns/:id/html which will either send an email or return HTML as a response.

More Details

Templates

Campaigns reference a templates, which are separate from the other endpoints in our system. Our templates take a blob of metadata in JSON format to create the interactive HTML. You can use the templates endpoint to get a list of all the available templates, get the default JSON object stored in the template, and use the preview endpoints here to get example HTML back. The example HTML from the preview endpoints will not contain campaign information, and points all reporting to a preview URL that will be discarded.

These are the endpoints that are available for you:

Templates Endpoint

Will return an array of all the templates available to your account

Will return the default JSON document for the specified template

Will return the HTML for the specified template, using the default JSON payload for the content to populate the template

Will return the HTML for the specified template. The request requires providing your own JSON payload for the content to populate the template

Note: The endpoints ending in /preview will return an HTML document, but that document will not be associated with a campaign, and when sent any reporting related to that email will be discarded by our systems.

Campaigns

Campaigns are the top level item in the stack, it contains the id (used throughout the system as reference), the ownerID (your account), the name, active template, integrations status (enabled or not), and top level stats.

These are the endpoints that are available for you:

Campaign Endpoints

Will return an array containing all the campaigns associated with your account

Is used to create a new campaign tied to your account, it requires just a name and an ownerId

Will return the campaign object for the specified campaign

Allows you to update the specified campaign. Only fields that are being updated are required

Will destroy the specified campaign

Sending

Once you have a campaign with an associated template you can get sending, there are two basic ways to send your interactive email. Either you used Rebelmail as a middleware, pinging our servers at the /email endpoint with JSON, we generate HTML using that metadata and then pass the HTML to a sender of your choosing, via a transactional API integration. Alternatively, you can use the /campaigns/:id/html endpoint with the same JSON blob. We will generate HTML for you and then pass the HTML back as a response to your request. Once you have the HTML back you can pass it through your ESP pipes as usual and send however you like.

These are the endpoints that are available for you:

Using Send Integrations

Will accept the same content JSON as a campaign, but will return a success message containing an :id and execute an email send via a send integration

Will return all the details of the specified email as well as a sentAt key for when the send was executed

Getting HTML Returned

Will return return the HTML generated by the content JSON stored in the specified campaign

Will return the HTML generated by the content JSON included in the request, using the specified campaign. Note: This will not replace the content JSON associated with the specified campaign


Sending with the API