• No results found

Octosend Documentation Documentation

N/A
N/A
Protected

Academic year: 2021

Share "Octosend Documentation Documentation"

Copied!
35
0
0

Loading.... (view fulltext now)

Full text

(1)

Octosend Documentation

Documentation

Release 3.0.0

Octosend Documentation Team

(2)
(3)

Contents

1 Getting Started 3

1.1 Prerequisites . . . 3

1.2 Choose your weapons . . . 4

2 HTTP API Integration 7 2.1 Overview . . . 7 2.2 Authentication . . . 9 2.3 Domains . . . 9 2.4 Campaign creation . . . 10 2.5 Campaigns retrieval . . . 16

2.6 Statistic and results . . . 18

3 PHP SDK Integration 21 3.1 Overview . . . 21 3.2 Install . . . 21 3.3 Authentication . . . 22 3.4 Domains . . . 22 3.5 Campaign creation . . . 23 3.6 Campaigns retrieval . . . 28

3.7 Statistic and results . . . 28

4 Customer Area Guide 31 4.1 Introduction . . . 31

(4)
(5)

Octosend Documentation Documentation, Release 3.0.0

Octosendis an innovative solution for big players to send a huge number of emails directly in the recipients inboxes. The core concepts ofOctosend are multi-routing and scoring to manage all of your email communication needs, either marketing email campaigns, transactional emails, trigger campaigns and more.

For more information on the product’s features, go see the Octosend landing page or feel free to contact us at hello@octosend.com. We are eager to get feedbacks and questions, whatever can help us improve our product, and we also love a good and relaxed chat sometimes.

Several interfaces allow you to access the product features and this documentation aims to guide you through the (we hope easy and we do everything we can for that !) task of integrating and using the service whatever your needs are. You need to know some informations and to get an account in order to get started. More on that in this introductory guide:

• Overall Presentation

Then you can get your hands dirty. We aim to ease the usage of our work and thus offer different ways to useOctosend. Those interfaces can be separated in regards of two users profiles:

• Developer Documentation

• User Guide

The developer documentation is for people who wants to use the features from their own softwares and GUI (at least for some parts of the product) while the user documentation aims to open all theOctosendfeatures to people who just want to take a quick look or don’t have the time or the development skills to have their own tools to manage their email campaigns.

But first things first, you need to complete some steps in theOverall Presentationbefore to dive in the integration of our cool features.

(6)
(7)

CHAPTER

1

Getting Started

Using Octosend is pretty simple and straightforward and you will get as much support as you need from the Octosend team.

However you need to complete some steps to get your account and start sending emails.

1.1 Prerequisites

1.1.1 Account creation

Whatever interface you will use to connect to Octosend and start using our shiny features, you will always need an Octosend account. You can get one by registering on the Octosend site or by contacting us directly at hello@octosend.com.

We will be happy to answer your questions and help you starting.

1.1.2 Domain delegation

Once your account is created, you are ready to connect to the customer area and to use the Octosend API either directly through the HTTP endpoints or by other interfaces.

Yet, you can not send real email. You need to perform some DNS configurations in order to delegate one (or more) domain of your choice, one that you own of course.

Say your top level domain is mydomain.tld, you can decide to delegate the subdomain octosend.mydomain.tld. Every registrar and domain name provider has its own way to configure and delegate a domain and/or subdomain, but the fundamental task is the same and follows the same logic: point your domain to the octosend DNS services. octosend.mydomain.tld. IN NS ns1.rmta-services.com.

octosend.mydomain.tld. IN NS ns2.rmta-services.com. octosend.mydomain.tld. IN NS ns3.rmta-services.com.

Note: You can delegate and configure on Octosend as many domain as you want. It can give you the possibility to use specific domains on specific databases or for particular campaigns (let’s say you want octosend.mydomain.tld but also newsletter.mydomain.tld, mail.mydomain.tld,... you can also have completely different domains configured, for example octosend.myotherdomain.tld,...)

Important: Domain delegation is a best practice for email campaigns. The domain is yours and clearly identify where does your campaign come from. Your reputation can grow with this domain. The delegation allows us to tell

(8)

the mail providers (those who provide email address to their users and use anti-spam tools to protect them) which IP is authorized to send emails from this domain and manage IP, reputation and signatures for the best.

1.2 Choose your weapons

Octosend features are intended for people who work with emails. We assume that most of you will be perfectly able and willing to understand and control what they do. For this, we offer several programmatic interfaces directly accessible from your own code.

Nevertheless, building a complete graphical user interface and email management software is not often a good solution and all of us want a good design and ergonomy to check their statistics, understand and analyze what going on ... maybe program the next campaign. That is why we also have a solution for this and it is worth to take a glimpse at our customer area.

Note: Of course, you can use whatever solution you like as your main tool or in parallel. For example, you can wire Octosend on your own CRM solution through the HTTP API and still consult your statistics on your customer area.

1.2.1 HTTP API

The HTTP API is the low level interface to access the Octosend features. It allows a perfect control of the ins and outs of deliverability and email campaigns management with Octosend.

It is reserved to advanced users who like to get their hands dirty and to understand perfectly what they do. Furthermore, it is intended to control everything from your side and your own softwares and codes.

You can find an http_api guide on this documentation and a complete reference is available at https://octosend.com/#/api.

1.2.2 Software Development Kits (SDK)

Software development kits are HTTP API client implementations in some popular languages. The abstractions pro-vided by the SDKs allows you to access Octosend features way more easily and to focus on your business.

It is the perfect compromise between getting ready quickly and easily and taking control over Octosend and integrating it directly in your own softwares and business layers.

All Octosend SDKs will be publicly released on thegithub project.

PHP SDK

The PHP SDK is our first implementation of an Octosend client in a specific language. It comes from the needs of our users and is designed to make it easy for a PHP coder to integrate easily our solution.

You can find the PHP SDK on its repository:https://github.com/octosend/php-sdk. The php_sdk guide can be found on this documentation and its sources are also publicly available onhttps://github.com/octosend/octosend-docsif you feel the soul to contribute.

(9)

Octosend Documentation Documentation, Release 3.0.0

Python SDK (coming really soon)

The python SDK is a core development of the Octosend team. We are currently working on it. The implementation is done and the team is currently testing and finalizing its work.

Let us know athello@octosend.comif you want to be kept posted about the release (before Christmas, that’s for sure !! May be a Christmas gift for your boss and/or your employees ?!).

Go SDK (coming soon)

Fellow programmers are yet working on a Go SDK that should be released soon. Do not hesitate to keep in touch directly athello@octosend.comif you want more insight on the advancement of this project.

Warning: This project is community driven, so the Octosend team can not guarantee an accurate delivery date.

Node.js SDK (coming soon)

Fellow programmers are yet working on a node.js SDK that should be released soon. Do not hesitate to keep in touch directly athello@octosend.comif you want more insight on the advancement of this project.

Warning: This project is community driven, so the Octosend team can not guarantee an accurate delivery date.

Note: If you want to contribute as some already are, feel free to contact us. We will be happy to open you an account and help you build a new client in a rare or unused programming language (ok, that works for every Octosend related project too)!

Important: We welcome all kind of contributions, either SDKs, plugins, ... developments that we can and will promote to our users, but also feedbacks, issues tracking, everything that can help us improve the product. Day to day, we work on this product with our users in mind and while we do our best, we need you to get better.

1.2.3 SMTP API (work in progress)

The SMTP API is designed to directly configure the SMTP transport protocol to use in your code and the authentication and then trigger directly email from your code.

It is particularly used to trigger transactional emails, those you have to send to confirm a payment or send login access for example. The power of Octosend will still remain available through Octosend reserved SMTP headers.

This work is still in progress and will be released soon (another Christmas gift... you will understand if you have read the whole page! otherwise, you can try and enjoy the documentation search feature).

1.2.4 Customer Area

The customer area is available after log in on the Octosend websitehttps://octosend.com. It is a web interface that provides the service in the Software as a Service style.

It aims to be as ergonomic and easy to understand as possible which means we are open to your feedback and that we will always improve it and likely fast! Go get an eye on it and let us know if you like it (or not) athello@octosend.com.

(10)
(11)

CHAPTER

2

HTTP API Integration

2.1 Overview

Octosendprovides a service to create and manage emailing campaigns. The user has one or several sending domains allowing him to create email campaigns (internally known as spoolers), to follow how they process and perform and to retrieve advanced statistics.

The HTTP API is the low level interface to the Octosend service and allows a fine control over the email sending operations. Advanced users can rely on the HTTP API to integrate Octosend to their own softwares or to code SDK, plugins and extensions.

2.1.1 Versions and reference

Each version of the API has its own url. The current stable version is v3.0 and is hosted at the url https://api.octosend.com/api/3.0/. The API exposes its methods as paths relative to this url.

TheAPI referencelists and documents all the methods available for a version of the API. While pretty arid at first, you will find that the API is not so hard to tackle. This integration documentation will guide you through common tasks allowing you to get familiar with the concepts and logic exposed.

2.1.2 Design

Global design

While not strictly a REST API, the Octosend HTTP API can be considered RESTful as it exposes resources through urls. For each resources, data and states (actions) can be accessed and retrieved. For the moment, the API mainly uses the HTTP verbs GET and POST to perform specific tasks.

The format used by the Octosend API is JSON either for the requests and the responses (JSON body).

Resources

The resources exposed by the API are:

(12)

domainand domains

Octosend allows you to use several sending domains and this resource allows to manage them spoolerand

spoolers

the spoolers represents you emailing campaigns, the abstraction in which you add all the informations for a specific campaign

statistics a shortcut entry point to access the metrics about your sending activity

events for each email (it means for each specific content sent to a given email address), you have access to events of several types such as routing or activity events. They are triggered when our routers, the email address providers or the recipients do some actions on the email.

timeline a convenience that provide a timed aggregated representation of your metrics scoring scoring is a resource able to note the elements you send to it

templates you can manage templates to recall later to build your contents

Some of those resources are business objects meant to be created (spoolers, domains, templates) while others allow to access data about those resources built during the routing process (scoring, statistics, timeline, events).

For the business objects the calls available on the collections of resources always adhere the following logic:

Method HTTP

verb

Example Description /<resources>/createPOST

/spool-ers/create

create a new resource instance /<resources>/fetchPOST

/spool-ers/fetch

retrieves an array of resource instances /<resources>/countGET

/spool-ers/count

count all the existing instances of the resource /<resources>/countPOST

/spool-ers/count

count all the existing instances of the resource matching the given criteria

Each type of resource has its own methods and specificities so we invite you to read the examples below to see how to perform some common operation or to check the fullAPI referenceto find what you are looking for.

Nevertheless, if you can not find how to do what you want do not hesitate to tell us onhello@octosend.comand we will enrich this documentation with examples to perform the task. Finally, you can ask for help onsupport@octosend.com and our support team will do its best to help you.

Important: Seriously, we really want to improve this documentation and will be more than happy to know your wish and requirements! You will receive a very quick answer and see that words will always be followed by deeds.

Errors

The API uses HTTP code for standard errors. The main errors are: Code Error Description

400 Bad Request

this code is mainly returned when there is an error in your body or other request elements 403 Forbidden this code is returned when you are not allowed to call a resource (seeAuthentication) 404 Not Found in the context of an API, it often means the resource (or method) called does not exist Additionally, you will get a JSON response with more details about the error, allowing a human or a program to process and log the errors.

2.1.3 HTTP Clients

Last words before to begin some calls. By design an HTTP API can be consumed by every http clients. This includes command line clients such ascURLorHTTPie, or programing languages specific standard or third party libraries. For

(13)

Octosend Documentation Documentation, Release 3.0.0

testing purpose you can also use browser plugins such asPostmanthat will let you test calls directly from you browser. Warning: All the examples of code provided are here to help understand how the HTTP API works. They are not production ready code and need to be performed with the HTTP client of you choice, error management, data persistence,...

2.2 Authentication

The authentication is a two step process. The first step is to explicitly call the authenticate method with you credentials as parameters.

The JSON body request is: {

"username": "woodstock",

"password": "twit***stoleme" }

where you need to put your own username and password. When you call the authenticate method with this body and valid credentials:

POST https://api.octosend.com/api/3.0/authenticate you will get the following JSON answer:

{

"api-key": "hash-string",

"entity": "Peanuts Inc",

"username": "woodstock" }

The api-key is the param you will use as the value of X-RMTA-API-Key for all other methods. As a second step you send the *X-RMTA-API-Key* header for every method.

Warning: In the following content, we will not tell you to send the X-RMTA-API-Key header again in order to simplify the explanations for each specific method. Don’t forget to add it or your calls will always receive a 403 HTTP response(see api-errors).

2.3 Domains

2.3.1 Domains list

Count the available domains

GET https://api.octosend.com/api/3.0/domains/count

Retrieve the first ten domains Body parameters

(14)

{

"limit": 10

}

sent on the domains/fetch method:

POST https://api.octosend.com/api/3.0/domains/fetch

will return a JSON array with matching domains as objects with a name property: [ { "name": "my.domain.tld" } ]

2.3.2 Filtering

This example shows how to retrieve the list of the user’s domains that contains the string “demo.” in the name of the domain. You just have to send:

{ "limit": 100, "nameContains": "demo.", "offset": 0, "reverse": false } on: POST https://api.octosend.com/api/3.0/domains/fetch

and you will be good.

As you have seen in the “first ten domains” example, you can send only the parameters you want. The available parameters are:

Param name Type Description

nameContains string a filter on the name of the domains Pagination params

limit integer the number of domains you want to retrieve offset integer starting point to skip some domains reverse boolean reverse order of the domains (alphabetical)

2.4 Campaign creation

2.4.1 Overview

Create a campaign

The first step is to create an empty spooler representing the campaign on a specific domain. Send the body

(15)

Octosend Documentation Documentation, Release 3.0.0

{

"domain": "my.domain.tld",

"type": "marketing" }

on the spoolers/create method:

POST https://api.octosend.com/api/3.0/spoolers/create This will return the representation of a new empty spooler:

{ "archived": false, "creation": 1, "domain": "my.domain.tld", "name": "", "start": 0, "state": "new", "token": "unique-idenfifier", "type": "marketing" }

where the token property is a hash unique identifier of your spooler you will use to perform every other calls on the spoolerresource.

Note: Every call to a spooler method will return this complete representation of the given spooler.

Set the name of the campaign

Let’s add some more information on your spooler. First set the name with: {

"name": "Your spooler name" }

on:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/name

Warning: The name is an important property to set in your workflow. It will allow you to identify the specific spoolerin your own words and to search and retrieve it later. By following some convention of your own, you will be able to get what you want easily.

Set the start date Then a start date with: { "start": <start-date-timestamp> } on: POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/start 2.4. Campaign creation 11

(16)

Note: If you provide the current timestamp as start date, the activation of the campaign with the /spooler/<current-spooler-token>/readymethod will send the campaign immediately while you can program your campaign to start at a specific date in the future (do not forget to activate your campaign still, more on that later).

Add your message

The next step is to define the content of this campaign. We do that by creating a message for which we specify several elements: the sender, the subject line, the parts of the message,...

The first thing to do is to set the contents that will be parts of the message: {

"type": "text/html",

"content": "<html>here is my html content</html>" }

to the spooler resources/part method:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/resources/part and your HTML content is set. The response return a string token that is the internal link to the posted content. It will be used later to set the parts to include in the message, so store it somewhere. For the example, we will call it: <html-content-part-token>

Now set the TEXT content: {

"type": "text/plain",

"content": "here is my text content", }

to the same resources/part method:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/resources/part

and we will call this token: <text-content-part-token>

Important: It is important you set both the HTML and the TEXT contents of your campaign with quality contents. While almost nobody (yes, some people with various goals in mind do it !) will read the TEXT version, it is always checked by the email address providers while checking for spams and may hurt your deliverability if not set with an appropriate content related to you HTML one!

You contents are ready, so you can build your message with all the elements by specifying them in the body of a call: {

"sender": "John Doe",

"subject": "Nice shoes for the winter",

"parts": [

"<html-content-part-token>", "<text-content-part-token>" ]

}

that you can send on the spooler message method:

(17)

Octosend Documentation Documentation, Release 3.0.0

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/message

Add some recipients

The spooler is now configured and the content is set. We have to add recipients. We create a mail with the recipient’s email address and we add this mail to the spooler. We say we “spool” a mail to the spooler.

{

"mails": [

{ "email": "octopus@deepsea.tld" } ]

}

To optimize the number of calls to the API, it is always a good idea to batch add recipients. This is pretty simple as it only requires to populate the mails array.

{ "mails": [ { "email": "snoopy@peanuts.tld" }, { "email": "charlie.brown@peanuts.tld" }, { "email": "woodstock@peanuts.tld" }, { "email": "flash@starlabs.tld" } ] }

Just send this body to the right spool method:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/spool and your recipients are set.

Send the campaign

The last step (yes you are almost done!) is to flag the spooler as ready to be send.

Note: Note that before this final step that lock the campaign and set it as ready, you can test your work at any time. It allows you to check how your message render on several email clients, to check the validity of the links or to get the validation for the final shoot. SeeTest your campaignsfor more information.

The Octosend system will trigger the launch of the campaign at the given start date:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/ready

Warning: After this call the campaign can not be modified anymore. Do not forgetTest your campaigns

2.4.2 Tracking variables

The content of the message can embed tracking variables that will be dynamically replaced (interpolated) when the mails will be formatted. If needed, it allows to track the events occurring on the emails of this campaigns.

Variables appear between double brackets in the contents and can be the following: • unsubscribe: an url allowing the recipients to unsubscribe from your list • mirror: an url allowing to see the content online

(18)

• click: an url allowing to redirect the recipients to the given target url while tracking the link activation (click count)

• pixel: an HTML tag allowing to track the opening of the emails by the recipients All occurs in the resources/part method we already seen before:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/resources/part

with the variables in the content string {

"type": "text/html",

"content": "<html>here my html content with

a <a href='{{unsubscribe}}'>unsubscribe link</a>, a <a href='{{mirror}}'>online version link</a>,

a <a href='{{click:http://www.yourdomain.tld/you-page}}'>click tracking link</a> and finally a {{pixel}} to track the open

</html>" }

and you are done!

Note: The {{pixel}} tracking variable is invisible and while is processed, does not appear to the user. You should not explicitly refer to it as we did in our example that will output : “and finally a to track the open”.

You can also redirect the unsubscribe link on an url on your side to display a custom unsubscribe page. {

"type": "text/html",

"content": "<html>here my html content with

a <a href='{{unsubscribe:http://www.yourdomain.tld/your-unsubscribe-page}}'> redirecting unsubscribe link</a>,

</html>" }

2.4.3 Customization variables

You can also create your own variables to customize the content of a message. The syntax is the same as for the tracking variables.

Content with tracking and customization: {

"type": "text/html",

"content": "<html>here my html content with

a <a href='{{unsubscribe}}'>unsubscribe link</a>, a <a href='{{mirror}}'>online version link</a>,

a <a href='{{click:http://www.yourdomain.tld/you-page}}'>click tracking link</a> and finally a {{pixel}} to track the open

and some variables to finish Dear {{firstname}} {{lastname}} </html>"

}

Customization variables can also be used in subject line:

(19)

Octosend Documentation Documentation, Release 3.0.0

{

"sender": "John Doe",

"subject": "beautiful shoes for you, {{firstname}}",

"parts": [

"<html-content-part-token>", "<text-content-part-token>" ]

}

{{firstname}}and {{lastname}} will be replaced by their values for each email. But where does those variables come from? The variables are linked for each recipients when you create and spool the recipients email address:

{ "mails": [ { "email": "charlie.brown@peanuts.tld", "variables": { "firstname": "Charlie", "lastname": "Brown" } }, { "email": "flash@starlabs.tld" "variables": { "firstname": "Barry", "lastname": "Allen" } } ] }

2.4.4 Test your campaigns

Depending on your workflow, there is good chances you want to test how your campaigns render before to seal your fate and send your message to all your targeted recipients.

Octosend provides an easy way to do it with a special method you can call at any time while editing your campaign (as long as you did not flag your campaign as ready).

You can do it by calling:

POST https://api.octosend.com/api/3.0/spooler/<current-spooler-token>/draft with the list of test emails on which you want to send the current version of your message:

{ "mails": [ { "email": "head@peanuts.tld", "variables": { "firstname": "Charlie", "lastname": "Brown" } }, { "email": "head-of-marketing@peanuts.tld" "variables": { "firstname": "Pal", 2.4. Campaign creation 15

(20)

"lastname": "Patine" }

} ] }

The method works exactly as the spool method except that the emails are sent immediately.

Warning: The test feature is only available to validate a campaign and make it “good for shooting”. Therefore the is strong limitations on what you can do ... or not. For instance, you are limited to 10 emails per draft method call.

2.5 Campaigns retrieval

2.5.1 Retrieve a campaign

At the creation, each campaign is assigned an unique identifier. This token identifier can be saved on the client side and allows to retrieve the campaign later:

GET https://api.octosend.com/api/3.0/spooler/<spooler-token> That will return the classic JSON representation of your campaign:

{

"archived": false,

"creation": 0,

"domain": "my.domain.tld",

"name": "My campaign",

"start": 5806512000,

"state": "finished",

"token": "unique-identifier",

"type": "marketing" }

2.5.2 List the first ten campaigns

Body parameters

{

"limit": 10

}

sent on the spoolers/fetch method:

POST https://api.octosend.com/api/3.0/spoolers/fetch

will return a JSON array with matching spoolers as objects with a spoolers properties: [

{

"domain": "my.domain.tld",

"name": "Awesome octopus to send your emails",

"tags": [],

"archived": 0,

(21)

Octosend Documentation Documentation, Release 3.0.0 "creation": 1440767231, "state": "new", "start": 1440767231, "token": "<current-spooler-token>", "type": "marketing" } ]

2.5.3 Filtering

The example shows how to retrieve the first ten new marketing campaigns from the domain my.domain.tld containing “promotion”in their names:

{ "createdAfter": 0, "createdBefore": 0, "domains": [ "my.domain.tld" ], "endAfter": 0, "endBefore": 0, "limit": 10, "nameContains": "promotion", "offset": 0, "reverse": false, "startAfter": 0, "startBefore": 0, "states": [ "new" ], "types": [ "marketing" ] }

While this body provides the full list of parameters for the example, you can off course, send only the parameters you want. The available parameters are:

(22)

Param name

Type Description Spoolers properties

nameContainsstring a filter on the name of the spoolers domains strings array an array of exact domains names

states strings array an array of spoolers status. The currently available states are “new”, “pending”, “running”, “cancelled”, “finished”

types strings array an array of types you are searching for. The currently available types are “marketing”or “transactional”

Pagination params

limit integer the number of spoolers you want to retrieve offset integer starting point to skip some spoolers reverse boolean reverse order of the spoolers (creation date) Date params

createdBeforeinteger (timestamp)

max timestamp boundaries on the creation date createdAfterinteger

(timestamp)

min timestamp boundaries on the creation date startBeforeinteger

(timestamp)

max timestamp boundaries on the start date startAfter integer

(timestamp)

min timestamp boundaries on the start date endBefore integer

(timestamp)

max timestamp boundaries on the end date endAfter integer

(timestamp)

min timestamp boundaries on the end date

2.6 Statistic and results

Once your campaign is launched, you can retrieve statistics for this campaign.

The statistics resource propose several aggregation type. The aggregation type changes the results you get from the API calls and group the data according to it.

Aggregation can be: router, router+domain, router+provider, domain, provider, global

• router: routers are the entities that route your emails. It can be the Octosend own routers or third party routers used with your agreement to improve the performance of your campaigns

• domain: domain in this context represents the recipients domains (yahoo.fr, yahoo.com, orange.fr,...)

• provider: provider represents the recipients high level domains grouped by entities (Microsoft = outlook.fr, outlook.com, hotmail.fr, etc.)

• router+domain: by router as described before, then by domain • router+provider: by router then by provider

For example call:

POST https://api.octosend.com/api/3.0/statistics/spooler/<spooler-token> with

{

"groupBy": "router+provider" }

(23)

Octosend Documentation Documentation, Release 3.0.0

You will get a JSON object with several counters of elements and events that occurred during you campaign processing. In “activity”, you will find the following activity counters:

• open: number of recipients that have opened the email

• click: number of recipients that have clicked a link in the email • mirror: number of recipients that are gone to the online version In “routing”, you will find the following routing counters:

• ok: number of messages delivered to their recipients

• tempfail: number of messages that could not be delivered but will be tried again later (ISP network issues,...) • permfail: number of messages that could not be delivered at all (non-existent addresses or domains,...) In “spooling”, you will find the following counters about your spooler:

• count: total number of messages spooled

• blocked: number of messages blocked for preventive reasons (preserve the ip, sending domain and campaign reputation from global blocking - spamtraps, already known non-existent addresses,...)

• quarantine: number of messages in quarantine

Note: After this guide you should be more confident to walk through theAPI Referenceand understand better how the API works. If you have any question or feedback aboutOctosendor this documentation the team will be happy to ear them athello@octosend.com. This documentation is a permanent work we want to improve and enrich with your feedbacks. You can also contribute directly to the documentation project, so feel free to take a look and send your pull requests athttps://github.com/octosend/octosend-docs.

(24)
(25)

CHAPTER

3

PHP SDK Integration

3.1 Overview

Octosendprovides a service to create and manage emailing campaigns. The user has one or several sending domains allowing him to create email campaigns (internally known as spoolers), to follow how they process and perform and to retrieve advanced statistics.

The PHP SDK is a PHP access layer on top of the HTTP API easing the use of the Octosend features through an object oriented mapping hiding the raw calls to the API.

All calls are managed by a single client object and its methods as a single straightforward entry point.

Warning: All the examples of code provided are here to help understand how the PHP SDK works. They are not production ready code which requires to catch errors and exceptions and other thing that will have cluttered our guide with complexity.

3.2 Install

Octosend follows standards and best practices for its PHP SDK and thus is available both on its octosend/php-sdk github repository and throughcomposerand thepackagist package repository.

You can install the latest version with

$ composer require octosend/php-sdk

Or add it as a dependency in your project composer.json file {

"require": {

"octosend/php-sdk": "^1.0" }

}

Then include thecomposerautoload file in your php script include 'vendor/autoload.php';

While we recommend to usecomposerwhich is the standard dependency manager in the PHP community you can also directly get the sources by cloning thegithub sources

(26)

$ git clone https://github.com/octosend/php-sdk.git

3.3 Authentication

First you need to authenticate against the Octosend API. $username = '...';

$password = '...';

$client = new OctoSend\Client($username, $password);

This call returns a client object from which all calls to the API will be made. This client is not connected, which means that the object does not store a permanent connection to the server during the life cycle of the object but connects at needs to perform the calls.

By default the SDK uses the production url of the API version matching the SDK release (currently v3.0 at the url https://api.octosend.com/api/3.0/). If you need, you can provide a specific url to use by the constructor:

$url = 'https://api.octosend.com/api/v3.x/';

$client = new OctoSend\Client($username, $password, $url);

3.4 Domains

3.4.1 Domains list

Count the available domains

$n = $client->domains()->count();

print_r($n);

Retrieve the first ten domains

$domains = $client->domains()->fetch(0, 10); foreach($domains as $domain) {

print_r($domain->name()); }

3.4.2 Filtering

This example shows how to retrieve the list of the user’s domains that contains the string “demo.” in the name of the domain

$filter = $client->domains(); $filter->nameContains('demo.');

print_r($filter->count());

$domains = $filter->fetch(0, 10); foreach($domains as $domain) {

print_r($domain->name()); }

(27)

Octosend Documentation Documentation, Release 3.0.0

3.5 Campaign creation

3.5.1 Overview

The first step is to choose the sending domain of the campaign. We directly retrieve the domain object by the domain name.

// retrieve a connector to a specific domain

$domain = $client->domain('demo.octosend.com');

Create a campaign

Then we create a spooler object representing the campaign and we give it a name and a start date.

// create and configure a campaign for this domain

$spooler = $domain->createSpooler('marketing');

// name of your choice, it allows you to recognize and search you campaign

$spooler->name('my campaign for the first integration test');

// give the campaign a timestamp as start date (24 hours later here)

$spooler->start(time() + 86400);

Every spooler get an unique identifier called “token” allowing to directly access the campaign later. $token = $spooler->token();

print_r($token); Set the content

The next step is to define the content of this campaign. We do that by creating a message object for the spooler for which we specify several elements: the sender, the subject line, the parts of the message,...

Once finished the message must be saved in the spooler. $message = $spooler->message();

$message->sender('John Doe');

$message->subject('Nice shoes for the winter'); $message->parts()->part(

'text/html',

'<html>here is my content</html>' );

$message->parts()->part( 'text/plain',

'here is my text content' );

// save your modification to the message in the spooler

$message->save();

Important: It is important you set both the HTML and the TEXT contents of your campaign with quality contents. While almost nobody (yes, some people with various goals in mind do it !) will read the TEXT version, it is always

(28)

checked by the email address providers while checking for spams and may hurt your deliverability if not set with an appropriate content related to you HTML one!

Add recipients

The spooler is now configured and the content is set. We have to add recipients. We create a mail with the recipient’s email address and we add this mail to the spooler. We say we “spool” a mail to the spooler.

$spooler->mail('octopus@deepsea.tld')->spool();

Batch add recipients

To optimize the number of calls to the API, it is always a good idea to batch add recipients. This is pretty simple but requires to create a batch object, to add the recipients to this batch object and then this object is spooled with only one call.

$batch = $spooler->batch();

$batch->mail('snoopy@peanuts.tld');

$batch->mail('charlie.brown@peanuts.tld'); $batch->mail('woodstock@peanuts.tld'); $batch->mail('flash@starlabs.tld'); $batch->spool();

Send the campaign

The last step (yes you are almost done!) is to flag the spooler as ready to be send. The Octosend system will trigger the launch of the campaign at the given start date.

Note: Note that before this final step that lock the campaign and set it as ready, you can test your work at any time. It allows you to check how your message render on several email clients, to check the validity of the links or to get the validation for the final shoot. SeeTest your campaignsfor more information.

$spooler->ready();

Warning: After this call the campaign can not be modified anymore. Do not forgetTest your campaigns

3.5.2 Test your campaigns

Depending on your workflow, there is good chances you want to test how your campaigns render before to seal your fate and send your message to all your targeted recipients.

Octosend provides an easy way to do it with a special method you can call at any time while editing your campaign (as long as you did not flag your campaign as ready).

You can test on every email created on a spooler with its draft method: $spooler->mail('octopus@deepsea.tld')->draft();

(29)

Octosend Documentation Documentation, Release 3.0.0

In the same way you spooled several email previous inBatch add recipients, you can test on several emails in one call, which is highly recommended.

$batch = $spooler->batch();

$batch->mail('snoopy@peanuts.tld');

$batch->mail('charlie.brown@peanuts.tld'); $batch->mail('woodstock@peanuts.tld'); $batch->mail('flash@starlabs.tld'); $batch->draft();

As you can see spool and draft methods are pretty close. The huge difference is the goal of each method and so how email are sent. draft send immediately when the call is performed to a limited number of recipient during the campaign creation. spool on its side only send email to the recipients when ready is called on a spooler and at the start date set.

Warning: The test feature is only available to validate a campaign and make it “good for shooting”. Therefore the is strong limitations on what you can do ... or not. For instance, you are limited to 10 emails per draft method call.

3.5.3 Tracking variables

The content of the message can embed tracking variables that will be dynamically replaced (interpolated) when the mails will be formatted. If needed, it allows to track the events occurring on the emails of this campaigns.

Variables appear between double brackets in the contents and can be the following: • unsubscribe: an url allowing the recipients to unsubscribe from your list • mirror: an url allowing to see the content online

• click: an url allowing to redirect the recipients to the given target url while tracking the link activation (click count)

• pixel: an HTML tag allowing to track the opening of the emails by the recipients

// message example with tracking

$message = $spooler->message(); $message->sender('John Doe');

$message->subject('Nice shoes for the summer'); $message->parts()->part(

'text/html',

"<html>here my html content with

a <a href='{{unsubscribe}}'>unsubscribe link</a>, a <a href='{{mirror}}'>online version link</a>,

a <a href='{{click:http://www.yourdomain.tld/you-page}}'>click tracking link</a> and finally a {{pixel}} to track the open

</html>" );

$message->parts()->part('text/plain', 'here is my text content'); $message->save();

Note: The {{pixel}} tracking variable is invisible and while is processed, does not appear to the user. You should not explicitly refer to it as we did in our example that will output : “and finally a to track the open”.

(30)

You can also redirect the unsubscribe link on an url on your side to display a custom unsubscribe page. $message->parts()->part(

'text/html',

"<html>here my html content with

a <a href='{{unsubscribe:http://www.yourdomain.tld/your-unsubscribe-page}}'> redirecting unsubscribe link</a>,

</html>" );

3.5.4 Customization variables

You can also create your own variables to customize the content of a message. The syntax is the same as for the tracking variables.

// message with tracking and customization

$message = $spooler->message(); $message->sender('John Doe');

$message->subject('beautiful shoes for you, {{firstname}}'); $message->parts()->part(

'text/html',

"<html>here my html content with

a <a href='{{unsubscribe}}'>unsubscribe link</a>, a <a href='{{mirror}}'>online version link</a>,

a <a href='{{click:http://www.yourdomain.tld/you-page}}'>click tracking link</a> a {{pixel}} to track the open

and some variables to finish Dear {{firstname}} {{lastname}} </html>"

);

$message->parts()->part('text/plain', 'here is my text content'); $message->save();

{{firstname}}and {{lastname}} will be replaced by their values for each email. But where does those variables come from? The variables are linked for each recipients when you create and spool the recipients email address:

// batch spool recipients with additional variables

$batch = $spooler->batch();

$mail = $batch->mail('charlie.brown@peanuts.tld'); $message = $mail->message();

$message->variables([ 'firstname' => 'Charlie', 'lastname' => 'Brown' ]);

$mail = $batch->mail('flash@starlabs.tld'); $message = $mail->message();

// oooops !

$message->variables([ 'firstname' => 'Barry', 'lastname' => 'Allen'

(31)

Octosend Documentation Documentation, Release 3.0.0

]);

$batch->spool();

3.5.5 Attachments

If you want to email invoices, payment receipts or other attachments meaningful for your clients, you can add those as part of the message for each email.

Note: In theory, you can send the same attachments to all you recipients through the spooler global message, but in most of the case, it will be a bad practice as design and other images used in the email should not be embedded as attachments but preferably hosted online.

First you create your mail with the spooler or with the batch spooler depending on the way you manage your recipient (let us remind that batch is the preferred way to do it). Then you get the message associated to this mail and finally the parts of this message to add the attachment part as raw content of you file.

Warning: Attachments are limited is size, type and context. First the attachments does not make sense for marketing campaigns and so are limited to transactional emails. Then the max size of the attachment is 2Mo, so we encourage you to keep your files small (nobody wants to receive a huge file in its inbox, except from friends maybe...). Finally, only the following types are allowed: application/pdf, application/json, image/jpeg, text/plain, text/html. If it is a problem for you, do not hesitate to contact us to tell us about your needs.

$mail = $batch->mail('charlie.brown@peanuts.tld');

// or $spooler->mail('charlie.brown@peanuts.tld');

$message = $mail->message(); $message->parts()->attachment(

'application/pdf',

file_get_contents('202001_charlie-brown_invoice.pdf'), 'invoice.pdf'

);

$mail = $batch->mail('flash@starlabs.tld'); $message = $mail->message();

$message->parts()->attachment( 'application/pdf',

file_get_contents('202001_barry-allen_invoice.pdf'), 'invoice.pdf'

);

Danger: If you get an exception while you think that everything is ok, first check the type of your campaign: as said earlier, attachments are forbidden on marketing campaign. Make sure your current spooler is transac-tional.

Tip: This method will work as soon as you get a mail, so this is the case for spooler mail creation and batch mail creation, but also in the context of draft and campaign testing.

(32)

3.6 Campaigns retrieval

3.6.1 Retrieve a campaign

At the creation, each campaign is assigned an unique identifier: $token = $spooler->token();

This token identifier can be saved on the client side and allows to retrieve the campaign later: $spooler = $client->spooler($token);

3.7 Statistic and results

Once your campaign is launched, you can retrieve statistics for this campaign. You first retrieve the campaign object. You then need to specify the aggregation type you desire. The aggregation type changes the results you get from the API calls and group the data according to it.

Aggregation can be: router, router+domain, router+provider, domain, provider, global

• router: routers are the entities that route your emails. It can be the Octosend own routers or third party routers used with your agreement to improve the performance of your campaigns

• domain: domain in this context represents the recipients domains (yahoo.fr, yahoo.com, orange.fr,...)

• provider: provider represents the recipients high level domains grouped by entities (Microsoft = outlook.fr, outlook.com, hotmail.fr, etc.)

• router+domain: by router as described before, then by domain • router+provider: by router then by provider

$aggregation = 'router+provider'; // or another one of the above

$statistics = $spooler->statistics($aggregation);

print_r($statistics);

You will get several counters of elements and events that occurred during you campaign processing. In “activity”, you will find the following activity counters:

• open: number of recipients that have opened the email

• click: number of recipients that have clicked a link in the email • mirror: number of recipients that are gone to the online version In “routing”, you will find the following routing counters:

• ok: number of messages delivered to their recipients

• tempfail: number of messages that could not be delivered but will be tried again later (ISP network issues,...) • permfail: number of messages that could not be delivered at all (non-existent addresses or domains,...) In “spooling”, you will find the following counters about your spooler:

• count: total number of messages spooled

• blocked: number of messages blocked for preventive reasons (preserve the ip, sending domain and campaign reputation from global blocking - spamtraps, already known non-existent addresses,...)

(33)

Octosend Documentation Documentation, Release 3.0.0

• quarantine: number of messages in quarantine

(34)
(35)

CHAPTER

4

Customer Area Guide

4.1 Introduction

Once your account is created onOctosend(see the getting_started guide for more information) you can connect to your customer area.

This interface allows you to access graphically to all the features of the product beginning by a Dashboard that give you a quick look on your emailing campaigns activity. You can see the big picture of your last campaign and how they deliver over the last month.

The web interface try to be as ergonomic as possible and we hope you will enjoy it and give us feedbacks to improve it day to day to get the perfect tool.

We will document some features with step by step visual guides and wait for your opinion about our product. Warning: The user guide is a work in progress. Every notice and remark are welcomed and feel free to contribute to thedoc repositoryif you like.

Important: We try to open publicly as much as we can of the product and work hard to release quality code, features, and in fine product. If you like who we are, the way we work, on what we work and want to help us and divert yourself by contributing for whatever reason you can possibly have, please do it and come to see us.

The publicly available parts are all released on the project github accounthttps://github.com/octosend(we will always share new things with the community) including this documentation and you can contribute either on the documenta-tion project, on the already existing projects or propose a new one. You can also help us by opening issues and tickets. Thanks!

References

Related documents

Members of the Marine Board Working Group on Marine Microbial Diversity at their meeting in Brussels on 10-11 February 2011, from left: Fergal O’Gara (BIOMERIT Research Centre,

Click Apply and then OK. Save the dataset. 17) Now that the base dataset is completed, the ASP wizard can be used to turn this into an ASP dataset. Click on Components

When the propagation direction is perpendicular to the magnetic field, solutions are identical to the case of a perpendicular magnetic field of field strength equal to strength of

Code Test Plans Reports User Documentation Word Processor Documentation Test Tools Testing Development Environment Coding CASE Tools Design CASE Tools Analysis Word

The Audit Division is headquartered in Portland, Maine and is comprised of a Director, Assistant Director, and two District Tax Audit Managers who.. supervise 9 audit teams headed

Predicting Longitudinal Dispersion Coefficient in Natural Streams Using M5´ Model Tree1. Amir Etemad-Shahidi 1 * and Milad Taghipour

· You are adding a user-defined field, as described in Creating User-Defined Fields, and you have opened the Field Data window to define the new field.. · The field type is

It is an open question whether for more than two agents with either additive, or separable and responsive preferences, efficient, individually rational, and weakly transfer- proof