Campaigns

Get all campaigns

GET /campaigns

Query string parameters

  • status string
    • Can be sent, draft or pending
  • type string
    • Can be email, telephone or letter
  • teams integer - Comma separated list of ids.
  • Supports Pagination
  • Supports Searching

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",
      "approved" : true,
      "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",
  "approved" : true,
  "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
  • approved bool    * default: true
  • type string
    • Can be email, letter or telephone
    • Required
  • message array
    • Required when approved is false    * Required when type is email or letter
    • message.content string     * Required when approved is false     * Required when type is email or letter**
    • message.subject string
      • Required when approved is false
      • Required when type is email
    • message.sender string
      • Required when approved is false
      • Required when type is email
  • filter
    • Supports filters section    * Required when approved is true
  • 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 if approved is not present or approved is true
  • 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",
  "approved" : true,
  "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",
  "approved" : true,
  "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
  • approved bool    * default: true
  • type string
    • Can be email, letter or telephone
    • Required
  • message array
    • Required when approved is false    * Required when type is email or letter
    • message.content string     * Required when approved is false     * Required when type is email or letter**
    • message.subject string
      • Required when approved is false
      • Required when type is email
    • message.sender string
      • Required when approved is false
      • Required when type is email
  • filter
    • Supports filters section    * Required when approved is true
  • 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 if approved is not present or approved is true
  • 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",
  "approved" : true,
  "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",
  "approved" : true,
  "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": "",
  "approved" : true,
  "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

Deprecated response fields

  • Following fields will be removed from the response 2018/10/01
  • template_id
  • subscribe_url
  • subject
  • content
  • help_text
{
  "domain": "easir.com",
  "domain_slug": "easir",
  "domain_slug_suffix": "easircampaigns.com",
  "consent": {
    "enable": true,
    "unsubscribe_url": "https://easir.com/unsubscribe"
  }
}

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.unsubscribe_url string - Consent URL for nonconsent. This will be used in the footer of campaign emails
    • Required when consent.custom is true

Deprecated parameters

  • Following parameters will be removed 2018/10/01
  • consent.subscribe_url string
  • consent.subject string
  • consent.content string
  • consent.help_text string
  • consent.template_id integer

Payload

{
  "domain_slug": "easir",
  "consent": {
    "enable": true,
    "unsubscribe_url": "https://easir.com/unsubscribe",
  }
}

Response
Status code 200

  • domain - Will be set if you have a custom domain to send campaigns from

Deprecated response fields

  • Following fields will be removed from the response 2018/10/01
  • template_id
  • subscribe_url
  • subject
  • content
  • help_text
{
  "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"
  }
}