Campaigns & Consent

Get all campaigns

GET /campaigns

Query string parameters

  • status string
    • Can be sent or pending
  • type string
    • Can be email, telephone or letter
  • Supports Pagination

Response
Status code 200

{
  "data": [
    {
      "id": "fab657f1-40de-4dec-bad5-a577ef4e4b05",
      "user": {
        "id": 1,
        "first_name": "Doe",
        "last_name": "John",
        "phone_number": "+4588888888",
        "job_title": "Animal",
        "email": "info@easir.com",
        "profile_picture": "http://api.randomuser.me/portraits/thumb/women/5.jpg",
        "created_at": "2014-01-01 12:45:56",
        "updated_at": "2014-01-02 00:11:22"
      },
      "name": "Campaign name",
      "description": "Some text to describe the campaign.",
      "type": "email",
      "message": {
        "subject": "Campaign subject"
      },
      "template": {
        "id": 2,
        "type": "email",
        "company_id": 1,
        "title": "Email template",
        "user_id": 1
      },
      "filter": [
        {
          "field": "contact.fixed_fields.last_name",
          "operator": "ct",
          "value": "e"
        }
      ],
      "sent_at": null,
      "send_at": "2015-11-30 00:00:00",
      "task": {
        "distribution_strategy": "distribute",
        "distribute_users": [
          {
            "id": 2,
            "first_name": "Florian",
            "last_name": "Walter",
            "phone_number": "300.010.4731x3314",
            "job_title": "Data Miner",
            "email": "something@example.com",
            "profile_picture": null,
            "created_at": "2014-09-16 01:23:22",
            "updated_at": "2015-02-11 10:58:41"
          }
        ],
        "relations_path": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
        "start_at": "2015-11-30 00:00:01",
        "end_at": "2015-11-30 00:00:02"
      },
      "created_at": "2015-07-29 11:20:32",
      "updated_at": "2015-07-29 11:20:32"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "per_page": 15,
    "urls": {
      "previous": null,
      "next": null
    }
  }
}

Get a campaign

GET /campaigns/:campaign_id

Response
Status code 200

{
  "id": "fab657f1-40de-4dec-bad5-a577ef4e4b05",
  "user": {
    "id": 1,
    "first_name": "Doe",
    "last_name": "John",
    "phone_number": "+4588888888",
    "job_title": "Animal",
    "email": "info@easir.com",
    "profile_picture": "http://api.randomuser.me/portraits/thumb/women/5.jpg",
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2014-01-02 00:11:22"
  },
  "name": "Campaign name",
  "description": "Some text to describe the campaign.",
  "type": "email",
  "message": {
    "subject": "Campaign subject",
    "content": "The content of the campaign body"
  },
  "template": {
    "id": 2,
    "type": "email",
    "company_id": 1,
    "title": "Email template",
    "user_id": 1
  },
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "sent_at": null,
  "send_at": "2015-11-30 00:00:00",
  "task": {
    "distribution_strategy": "distribute",
    "distribute_users": [
      {
        "id": 2,
        "first_name": "Florian",
        "last_name": "Walter",
        "phone_number": "300.010.4731x3314",
        "job_title": "Data Miner",
        "email": "something@example.com",
        "profile_picture": null,
        "created_at": "2014-09-16 01:23:22",
        "updated_at": "2015-02-11 10:58:41"
      }
    ],
    "relations_path": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
    "start_at": "2015-11-30 00:00:01",
    "end_at": "2015-11-30 00:00:02"
  },
  "created_at": "2015-07-29 11:20:32",
  "updated_at": "2015-07-29 11:20:32"
}

Create a campaign

POST /campaigns

Note that a campaign domain will have to be set in the campaign settings before a campaign can be created.

Parameters

  • name string
    • Required
  • description string
  • type string
    • Can be email, letter or telephone
    • Required
  • message.content string
    • Required when type is email or letter
  • message.subject string
    • Required when type is email
  • message.sender string
    • Required when type is email
  • filter
    • Supports filters section
    • Required
  • template_id integer
    • Must be a valid template id, and the template type must match the type
  • send_at date
    • Y-m-d H:i:s format
    • Must be after now
    • Required
  • task.distribution_strategy string
    • Must be distribute
    • More will be added in the future
    • Required if task is present
  • task.distribute_users array
    • Required if task is present
  • task.relations_path UUID
    • Must be a valid relations path id.
    • Required if task is present
  • task.start_at date
    • Y-m-d H:i:s format
    • Must be after send_at
    • Required if task is present
  • task.end_at date
    • Y-m-d H:i:s format
    • Must be after task.start_at
    • Required if task is present

Payload

{
  "name": "My campaign",
  "description": "Some text to describe this campaign",
  "type": "email",
  "message": {
    "content": "This is my content",
    "subject": "This is my subject",
    "sender": "example@easir.com"
  },
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "template_id": 2,
  "send_at": "2016-11-30 00:00:00",
  "task": {
    "distribution_strategy": "responsible_user",
    "distribute_users": [4, 10, 34],
    "relations_path": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
    "start_at": "2016-11-30 00:00:01",
    "end_at": "2016-11-30 00:00:02"
  }
}

Response
Status code 201

{
  "id": "60318269-aeec-4284-a6c1-10ca6ff38d68",
  "user": {
    "id": 1,
    "first_name": "Doe",
    "last_name": "John",
    "phone_number": "+4588888888",
    "job_title": "Animal",
    "email": "info@easir.com",
    "profile_picture": "http://api.randomuser.me/portraits/thumb/women/5.jpg",
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2014-01-02 00:11:22"
  },
  "name": "My campaign",
  "description": "Some text to describe this campaign",
  "type": "email",
  "message": {
    "content": "This is my content",
    "subject": "This is my subject"
  },
  "template": {
    "id": 2,
    "type": "email",
    "company_id": 1,
    "title": "Email template",
    "user_id": 1
  },
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "sent_at": null,
  "send_at": "2016-11-30 00:00:00",
  "task": {
    "distribution_strategy": "responsible_user",
    "distribute_users": [
      {
        "id": 4,
        "first_name": "Dorris",
        "last_name": "Hane",
        "phone_number": "459-677-4978x26093",
        "job_title": "Chief Data Officer",
        "email": "dorris@easir.com",
        "profile_picture": null,
        "created_at": "2015-03-23 14:25:07",
        "updated_at": "2015-06-16 13:43:17"
      }
    ],
    "relations_path": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
    "start_at": "2016-11-30 00:00:01",
    "end_at": "2016-11-30 00:00:02"
  },
  "created_at": "2015-07-30 07:01:24",
  "updated_at": "2015-07-30 07:01:24"
}

Update a campaign

PUT /campaigns/:campaign_id

Note: You can't update a campaign that is already sent

Parameters

  • name string
    • Required
  • description string
  • type string
    • Can be email, letter or telephone
    • Required
  • message.content string
    • Required when type is email or letter
  • message.subject string
    • Required when type is email
  • message.sender string
    • Required when type is email
  • filter
    • Supports filters section
    • Required
  • template_id integer
    • Must be a valid template id, and the template type must match the type
  • send_at date
    • Y-m-d H:i:s format
    • Must be after now
    • Required
  • task.distribution_strategy string
    • Must be distribute
    • More will be added in the future
    • Required if task is present
  • task.distribute_users array
    • Required if task is present
  • task.relations_path UUID
    • Must be a valid relations path id.
    • Required if task is present
  • task.start_at date
    • Y-m-d H:i:s format
    • Must be after send_at
    • Required if task is present
  • task.end_at date
    • Y-m-d H:i:s format
    • Must be after task.start_at
    • Required if task is present

Payload

{
  "name": "My campaign",
  "description": "Some text to describe this campaign",
  "type": "email",
  "message": {
    "content": "This is my content",
    "subject": "This is my subject",
    "sender": "example@easir.com"
  },
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "template_id": 2,
  "send_at": "2016-11-30 00:00:00",
  "task": {
    "distribution_strategy": "responsible_user",
    "distribute_users": [4, 10, 34],
    "relations_path": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
    "start_at": "2016-11-30 00:00:01",
    "end_at": "2016-11-30 00:00:02"
  }
}

Response
Status code 200

{
  "name": "My campaign",
  "description": "Some text to describe this campaign",
  "type": "email",
  "message": {
    "content": "This is my content",
    "subject": "This is my subject"
  },
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "template_id": 2,
  "send_at": "2016-11-30 00:00:00",
  "task": {
    "distribution_strategy": "responsible_user",
    "distribute_users": [4, 10, 34],
    "relations_path": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
    "start_at": "2016-11-30 00:00:01",
    "end_at": "2016-11-30 00:00:02"
  }
}

Copy a campaign

POST /campaigns/:campaign_id/copy

Response
Status code 204

{
  "id": "ed065b6b-36e1-4849-9a4b-7e4aa884e96a",
  "user": {
    "id": 1,
    "first_name": "Doe",
    "last_name": "John",
    "phone_number": "+4588888888",
    "job_title": "Animal",
    "email": "info@easir.com",
    "email_notifications": false,
    "profile_picture": "http://api.randomuser.me/portraits/thumb/women/5.jpg",
    "created_at": "2016-01-01 12:45:56",
    "updated_at": "2017-01-02 00:11:22"
  },
  "name": "a campaign - copy",
  "description": "",
  "type": "email",
  "message": {
    "content": "fasko da ero va",
    "subject": "Lorem ipsum",
    "sender": "sa29@example.com"
  },
  "template": null,
  "filter": [
    {
      "field": "contact.fixed_fields.email",
      "value": "@easir.com",
      "operator": "ct"
    }
  ],
  "sent_at": null,
  "send_at": null,
  "task": null,
  "created_at": "2015-09-17 11:21:14",
  "updated_at": "2015-09-17 11:21:14"
}

Delete a campaign

DELETE /campaigns/:campaign_id

You can't delete a campaign that is already sent!

Response
Status code 204

Get campaign messages

GET /campaigns/:campaign_id/messages/:campaign_message_id

When sending a email or letter campaign, you can get the actual content sent to a contact.

Response
Status code 200

{
  "id": 1,
  "campaign_id": "1390836c-5817-4c4d-897f-68c825005528",
  "contact_id": "bf42dead-59df-472c-8ead-423012d12c23",
  "content": "Campaign content",
  "created_at": "2016-06-16 09:57:29",
  "updated_at": "2016-06-16 09:57:29"
}

Letter campaign

GET /campaigns/:campaign_id/letters

If your campaign is of type letter you will recieve a notification when we have created the PDF's. When we are done, you can get a URL to a ZIP file with the PDF's. The URL is valid for 5 minutes!

Response
Status code 200

{
  "url": "http://example.com/download_url"
}

Preview

This endpoint is deprecated and will be removed Feburary 1st, 2018. The Preview Template endpoint can be used instead.

POST /campaigns/preview

The request is the same as creating a campaign, but a different endpoint.

Parameters

Response
Status code 200

{
  "download_url": "http://example.com/campaign.html"
}

Send test email

POST /campaigns/test-email

The request is the same as creating a campaign, but a different endpoint.

Parameters

Response
Status code 202 Queued

{
  "email": "john.doe@example.com"
}

Preview existing

This endpoint is deprecated and will be removed Feburary 1st, 2018. The Preview Template endpoint can be used instead.

GET /campaigns/:campaign_id/preview

Returns a URL to a preview of the campaign letter or email.

Response
Status code 200

{
  "download_url": "http://example.com/campaign.html"
}

Send test email for existing

POST /campaigns/:campaign_id/test-email

Sends a mail with the campaign to a user-specified email for testing purposes.

Parameters

  • email - string
    • Required

Payload

{
  "email": "john.doe@example.com"
}

Response
Status code 202 Queued

{
  "email": "john.doe@example.com"
}

Campaign settings

GET /campaigns/settings

Campaign domains

Campaigns can either be sent from a custom domain (domain property), or using a subdomain of the easircampaigns.com domain (domain_slug property).

The custom domain will have the first priority, and if that isn't set, emails will have a from address in the form of noreply@[domain_slug].easircampaigns.com.

Either domain or domain_slug will have to be set in order to create campaigns.

Response
Status code 200

{
  "domain": "easir.com",
  "domain_slug": "easir",
  "domain_slug_suffix": "easircampaigns.com",
  "consent": {
    "enable": true,
    "template_id": 2,
    "subscribe_url": "https://easir.com/subscribe",
    "unsubscribe_url": "https://easir.com/unsubscribe",
    "subject": "subject",
    "content": "content",
    "help_text": "help text"
  }
}

Set campaign settings

PUT /campaigns/settings

Parameters

Campaign domain

  • domain_slug string - The subdomain to send campaigns from. Will result in campaigns being sent from [domain_slug].easircampaigns.com

Custom consent settigns

  • consent.custom boolean - Enable custom consent settings
  • consent.subscribe_url string - Consent URL for positive consent. This will be used for the link to accept consent in consent request emails. Merge fields can be used
    • Required when consent.custom is true
  • consent.unsubscribe_url string - Consent URL for nonconsent. This will be used in the footer of campaign emails
    • Required when consent.custom is true
  • consent.subject string - Subject of consent request emails. Merge fields can be used
    • Required when consent.custom is true
  • consent.content string - Content of consent request emails. Merge fields can be used
    • Required when consent.custom is true
  • consent.help_text string - Help text for EASI’R users. Shown before clicking "Request Consent" on a Contact page in the EASI'R frontend
  • consent.template_id integer - Set a custom template to be used for consent request emails.
    • Must be of type email.

Payload

{
  "domain_slug": "easir",
  "consent": {
    "enable": true,
    "template_id": 2,
    "subscribe_url": "https://easir.com/subscribe",
    "unsubscribe_url": "https://easir.com/unsubscribe",
    "subject": "subject",
    "content": "content",
    "help_text": "help text"
  }
}

Response
Status code 200

  • domain - Will be set if you have a custom domain to send campaigns from
{
  "domain": "https://easir.com",
  "domain_slug": "easir",
  "consent": {
    "enable": true,
    "template_id": 2,
    "subscribe_url": "https://easir.com/subscribe",
    "unsubscribe_url": "https://easir.com/unsubscribe",
    "subject": "subject",
    "content": "content",
    "help_text": "help text"
  }
}

Consent

Consent (also known as Permissions) is the way Contacts give consent for receiving campaign emails. By default, EASI'R uses double-opt in for consent, which means contacts must always explicitly give consent to receiving campaigns. EASI'R also stores a log of all changes to the consent status of a Contact. When a contact is created, the consent status is false per default.

All campaign mails, whether or not Custom Consent is used, will have an unsubscribe link appended to the end of the email, as well of subscriber details like date of subscription and the subcriber's IP address.

When consent status is updated

  • A user of EASI’R requests consent from a Contact, and the Contact clicks on "give consent" or "don't give consent".
  • A user clicks the Unsubscribe link in a Campaign email
  • By API call (described below)

Consent status

  • false - Contact has stopped giving consent (default)
  • true - Contact has given consent to receiving campaigns

Consent sources

Type name Description
default Set upon contact creation
contact Set by the contact, e.g. unsubscribe link, consent request
api Updated by an API request
import Set during import
email_change Consent is revoked when e-mail address is changed
bounce Consent is revoked after 3 hard bounces

Timeline events

The following timeline events are added to a contact during the consent process:

Event name Description
consent_sent The consent email was successfully sent
consent_open The consent email was opened by the contact
consent_failed The consent email could not be delivered
consent_created Consent was updated by contact, API, etc.

Custom Consent has been designed to give EASI'R users control over the consent process to provide a more customized experience for their users. Admins can configure Custom Consent in the Settings area in EASI'R under Settings > Campaigns > Settings. EASI'R allows users to customize these parts of the consent process:

  • The consent request email template - a normal EASI'R template can be used
  • The consent request email contents and subject
  • The unsubscribe and subscribe links in consent requests and campaign emails

Unsubscribe and subscribe links

With custom consent links, you will be responsible for creating and maintaining a web application that will update the consent status of the contact in EASI'R using the EASI'R API. This will allow you to show your own confirmation page and update the consent status in third-party systems.

The links can contain merge fields, which allow other applications to know details of the contact that accepted or denied consent. For example, a consent URL could be in the following format:

https://consent.example.com/accept?account_id={{b2c_account.id}}{{account.id}}
    &contact_id={{b2c_contact.id}}{{contact.id}}
    &first_name={{b2c_contact.fixed_fields_first_name}}{{contact.fixed_fields_first_name}}
    &internal_id={{b2c_contact.custom_fields_internal_id}}{{contact.custom_fields_internal_id}}

This will provide the neccessary IDs to perform a manual consent change with our API (see Set consent section), as well as the ability to display the contact's name on the web page. Custom fields can also be added. For example, if an external reference to a contact is stored as a custom field in EASI'R, this could be used to update the consent status of the contact in third-party systems.

POST /accounts/:accountId/contacts/:contactId/consent/request

Sending a request to this endpoint will send a mail to the Contact's email address (determined from the fixed field). The email will contain two links, "give consent" and "don't give consent". Both links will set the consent property on the Contact itself as well as adding an item in the Contact's consent log.

Response
Status code 204

GET /accounts/:accountId/contacts/:contactId/consent

In this example, the latest, and currently valid, consent is displayed at the top. On 03/30, a user updated the consent for the user by the API, and on 03/31 the consent was set by the contact from a consent link in an email.

Response
Status code 200

{
  "data": [
    {
      "id": 3,
      "user_id": 1,
      "contact_id": "8dbb05f9-e19c-34f8-8885-eed4e520bf3c",
      "campaign_id": null,
      "status": false,
      "type": null,
      "source": "contact",
      "contact_ip": "33.33.33.1",
      "contact_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/601.5.17 (KHTML, like Gecko) Version/9.1 Safari/601.5.17",
      "created_at": "2016-03-31 09:05:26"
    },
    {
      "id": 1,
      "user_id": 1,
      "contact_id": "8dbb05f9-e19c-34f8-8885-eed4e520bf3c",
      "campaign_id": null,
      "status": true,
      "type": null,
      "source": "api",
      "contact_ip": null,
      "contact_user_agent": null,
      "created_at": "2016-03-30 09:00:34"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "per_page": 15,
    "urls": {
      "previous": null,
      "next": null
    }
  }
}

POST /accounts/:accountId/contacts/:contactId/consent

Status determines whether consent is given (true) or not given (false).

Setting the consent will log within the consent log the user which has carried out the action, and that it was carried out using the API.

Parameters

  • status boolean - Determines whether consent is given or not.

Payload

{
  "status": true
}

Response
Status code 200

{
  "id": 5,
  "user_id": 1,
  "contact_id": "8dbb05f9-e19c-34f8-8885-eed4e520bf3c",
  "campaign_id": null,
  "status": true,
  "type": null,
  "source": "api",
  "contact_ip": null,
  "contact_user_agent": null,
  "created_at": "2016-03-30 09:08:59"
}