Back to top

Rule

This is the documentation for the Rule v2 api. If you find anything unclear or incorrect, please let us know by dropping an email to: [email protected]

If you are looking for documentation on v1 of the api, you can find it here

Overview

Authentication

To be able to use the API you first have to obtain an api key from your accounts settings page.

Once the api key has been generated it can be used in the following ways when making requests.

Passed as a get parameter:

?apikey=YOUR-API-KEY_HERE

Passed as part of the request body:

apikey: YOUR-API-KEY-HERE

Passed as an header:

Authorization: Bearer YOUR-API-KEY-HERE

Failed authorization will result in a 401 response:

{
    "error": "NotAuthorized"
}

Pagination

Actions that requests all items of a resource will be paginated. The pagination can be customized to tour liking by changing the limit parameter to only fetch a desired amount of items. The limit can Not exceed 100 items.

Exceeding the limit limitation will result in a 400 response:

{
    "error": "LimitExceed",
    "message": "Limit can't exceed 100."
}

Each paginated action will return a meta section in the response. The meta section will consist of a link to get the next page.

The link is populated with all necessary attributes so you can simply follow the link directly to get the next set of items.

Example of meta section:

{
    "meta": {
        "next": "https://app.rule.io/api/v2/subscribers?limit=100&cursor=MQ==&apikey=YOUR-API-KEY-HERE"
    }
}

Error handling

Each action specifies any given errors that can occur during the request and consists of mostly validation errors.

Sometimes unexpected errors can occur, and when they do a 500 response will be returned.

{
    "error": "UnexpectedError",
    "message": "An unexpected error occurred. Contact support if the error persists."
}

When this happens send a support request to: [email protected] with a description of how the error occurred.

Rate limit

Some actions in the API are rate limited. This means that we only let through a limited amount of request based on action/consumer/time.

As an example an action can have a limit of 100 attempts (request) / 60 seconds.

If you exceed the given rate limite on an action you will recieve a 429 response:

Too Many Attempts.

Along with the resposne the following custom headers will be available:

  • X-RateLimit-Limit - Will show the maximum number of attempts for the action

  • X-RateLimit-Remaining - Will show the number of attemps remaining

  • Retry-After - Will show the number of seconds until further attempts are allowed again

The following actions are rate limited:

action attempts seconds
POST /subscribers 100 60

Subscribers

Create new subscriber

Create subscriber
POST/subscribers

Attributes

  • update_on_duplicate - (optional) defaults to false if omitted.

  • automation - (optional) Defaults to false if omitted.

  • tags - can consist of both names and/or ID’s of already existing tags. If a tag does not exist it will be created.

  • language - (optional) Needs to be ISO 639-1 formatted. If no language is passed the subscriber will default to the account language.

  • phone_number - (required without email)

  • email - (required without phone_number)

Field types

  • The “field key” have to formatted as: GroupName.FieldName. Both the group and the field will be created if they don’t exist. The field name can’t consist of email, phone_number or contain a .

  • The field type attribute is not required and will default to text if omitted.

  • Valid field types are:

    • text
    • date
    • datetime
    • multiple
    • json

When using the multiple type you have to pass in the values as an array. E.g ['Item1', 'Item2']

To be certain of correct phone number formatting the phone_number attribute should be prefixed with an valid country code. E.g +46 If no prefix is given we will try to parse the number as a Swedish number.

opt in

An opt in flow can be trigger by passing require_opt_in: true as an attribute. For this to work a sign up flow in Rule have to be created first. On or more tag used to create the subscriber have to be tied to a sign up flow in Rule fot the optin to function.

Consult the Rule manual for more information about createing sign up flows.

If no opt in flow can be found the subscriber will be automatically opted in.

automation

By passing automation: reset in the request, automation flows will be reset for all tags and segments based on the tags in the request that matches, even if the subscriber already belongs to provided tags. For each automation flow that gets reset, previously scheduled messages will be removed.

Passing automation: force in the request, will trigger a new automation flow for all tags and matching segments based on the request tags, even if the subscriber already belongs to provided tags. Previously scheduled messages from the automation flows triggered will not be removed.

Example URI

POST https://app.rule.io/api/v2/subscribers
Request  create
HideShow
Headers
Content-Type: application/json
Body
{
  "update_on_duplicate": true,
  "tags": [
    "Test Tag"
  ],
  "subscribers": {
    "email": "[email protected]",
    "phone_number": "+46123456789",
    "language": "sv",
    "fields": [
      {
        "key": "Group.FirstName",
        "value": "John",
        "type": "text"
      },
      {
        "key": "Group.Items",
        "value": [
          "Item1",
          "Item2"
        ],
        "type": "multiple"
      },
      {
        "key": "Group.Created",
        "value": "2016-03-20 12:00:00",
        "type": "datetime"
      }
    ]
  }
}
Request  create multiple
HideShow

Create multiple subscribers at once.

Creating multiple subscribers can be slow. Therefore this request will be handled asynchronously. If you for some reason don’t want that behavior, you can pass async: false as part of the request.

Headers
Content-Type: application/json
Body
{
  "update_on_duplicate": true,
  "tags": [
    "Test Tag"
  ],
  "subscribers": [
    {
      "email": "[email protected]",
      "phone_number": "+46123456789",
      "fields": [
        {
          "key": "Group.FirstName",
          "value": "John",
          "type": "text"
        },
        {
          "key": "Group.Items",
          "value": [
            "Item1",
            "Item2"
          ],
          "type": "multiple"
        },
        {
          "key": "Group.Created",
          "value": "2016-03-20 12:00:00",
          "type": "datetime"
        }
      ]
    },
    {
      "email": "[email protected]",
      "phone_number": "+46123456987",
      "fields": [
        {
          "key": "Group.FirstName",
          "value": "Jane",
          "type": "text"
        },
        {
          "key": "Group.Items",
          "value": [
            "Item1",
            "Item2"
          ],
          "type": "multiple"
        },
        {
          "key": "Group.Created",
          "value": "2016-03-20 12:00:00",
          "type": "datetime"
        }
      ]
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success",
  "subscriber": {
    "id": "1",
    "email": "[email protected]",
    "phone_number": "+46123456789",
    "language": "sv",
    "created_at": "2016-03-20 12:00:00",
    "updated_at": "2016-03-20 12:00:00",
    "tags": [
      {
        "id": "1",
        "name": "Test tag"
      }
    ]
  },
  "suppressed": []
}
Response  409
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "DuplicateSubscriber",
  "message": "Subscriber already exists"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "BadRequest",
    "message": "Some fields could not be validated",
    "fields": {
        "email": ["The email field is required when phone number is not present."]
    }
}

{
    "error": "InvalidFieldName",
    "message": "Invalid name given. Email & phone_number are reserved keyword."
}

{
    "error": "InvalidFieldType",
    "message": "Invalid type given. Valid types are: [text, single, multiple, json, datetime, date, time]."
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "TagNotFound",
  "message": "Cound not find tag with given ID."
}
Response  413
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "RequestEntityTooLarge",
  "message": "Max 1000 subscribers per call allowed."
}

Get subscribers

Get subscribers
GET/subscribers{?limit}

Example URI

GET https://app.rule.io/api/v2/subscribers?limit=20
URI Parameters
HideShow
limit
number (optional) Example: 20

Number of subscribers to fetch. Defaults to 100 and can’t exceed 100.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "subscribers": [
    {
      "id": 1,
      "email": "[email protected]",
      "phone_number": "+46123456789",
      "language": "sv",
      "opted_in": true,
      "created_at": "2016-03-22 12:00:00",
      "updated_at": "2016-03-22 12:00:00",
      "tags": [
        {
          "id": 1,
          "name": "Newsletter"
        }
      ],
      "suppressed": []
    },
    {
      "id": 2,
      "email": "[email protected]",
      "phone_number": "+461234567987",
      "language": "sv",
      "opted_in": true,
      "created_at": "2016-03-22 12:00:00",
      "updated_at": "2016-03-22 12:00:00",
      "tags": [
        {
          "id": 1,
          "name": "Newsletter"
        }
      ],
      "suppressed": []
    }
  ],
  "meta": {
    "next": "https://app.rule.io/api/v2/subscribers?cursor=2&limit=3"
  }
}

Get subscriber

Get subscriber
GET/subscribers/{identifier}{?identified_by}

Example URI

GET https://app.rule.io/api/v2/subscribers/[email protected]?identified_by=email
URI Parameters
HideShow
identifier
enum (required) Example: [email protected]
  • id (number) - ID belonging to a subscriber.

  • email (string) - Email belonging to a subscriber.

  • phone_number (string) - Phone number belonging to a subscriber. Make sure to urlencode the input.

identified_by
string (optional) Example: email

Specify your identifier, ID, phone number or email (default: email)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "subscriber": {
    "id": "1",
    "email": "[email protected]",
    "phone_number": "+46123456789",
    "language": "sv",
    "opted_in": true,
    "created_at": "2016-03-20 12:00:00",
    "updated_at": "2016-03-20 12:00:00",
    "tags": [
      {
        "id": "1",
        "name": "Newsletter"
      }
    ],
    "suppressed": []
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "NotFound",
  "message": "Could not find subscriber with given identifier."
}

Get subscriber fields

Get subscriber fields
GET/subscriber/{identifier}/fields{?identified_by}

Example URI

GET https://app.rule.io/api/v2/subscriber/[email protected]/fields?identified_by=email
URI Parameters
HideShow
identifier
enum (required) Example: [email protected]
  • id (number) - ID belonging to a subscriber.

  • email (string) - Email belonging to a subscriber.

  • phone_number (string) - Phone number belonging to a subscriber. Make sure to urlencode the input.

identified_by
string (optional) Example: email

Specify your identifier, ID, phone number or email (default: email)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success",
  "groups": [
    {
      "name": "Member",
      "historical": false,
      "fields": [
        {
          "id": 1,
          "name": "FirstName",
          "value": "John",
          "type": "text"
        }
      ]
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "NotFound",
  "message": "Could not find subscriber with given identifier."
}

Update subscriber

Update subscriber
PUT/subscribers/{identifier}

All attributes in this request are optional. So you can choose which attributes you want to update and skip the rest.

Example URI

PUT https://app.rule.io/api/v2/subscribers/1
URI Parameters
HideShow
identifier
number (required) Example: 1

ID for subscriber to get.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "[email protected]",
  "phone_number": "+46123456789",
  "language": "sv",
  "tags": [
    "Newsletter"
  ],
  "fields": [
    {
      "key": "Member.FirstName",
      "value": "John",
      "type": "text"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success",
  "subscriber": {
    "id": 1,
    "email": "[email protected]",
    "phone_number": "+46123456789",
    "language": "sv",
    "opted_in": true,
    "tags": [
      {
        "id": 1,
        "name": "Newsletter"
      }
    ],
    "suppressed": []
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "BadRequest",
    "message": "Some fields could not be validated.",
    "fields": {
        "email": ["The email field is required when phone number is not present."]
    }
}

{
    "error": "BadRequest",
    "message": "Invalid language."
}

{
    "error": "BadRequest",
    "message": "Invalid phone number."
}

{
    "error": "InvalidFieldName",
    "message": "Invalid name given. Email & phone_number are reserved keyword."
}

{
    "error": "InvalidFieldType",
    "message": "Invalid type given. Valid types are: [text, single, multiple, json, datetime, date, time]."
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "SubscriberNotFound",
    "message": "Subscriber with provided id could not be found"
}

{
    "error": "TagNotFound",
    "message": "ould not find tag with given ID."
}
Response  409
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "BadRequest",
  "message": "A subscriber with given email/phone_number already exists."
}

Tags

Add tag
POST/subscribers/{identifier}/tags{?identified_by}

If a tag does not exist and the tag identifier is of type string, it’ll be automatically created.

This action will trigger automation flows when the tag is added to the subscriber and an automation flow is active on given tag.

Example URI

POST https://app.rule.io/api/v2/subscribers/[email protected]/tags?identified_by=email
URI Parameters
HideShow
identifier
enum (required) Example: [email protected]
  • id (number) - ID belonging to a subscriber.

  • email (string) - Email belonging to a subscriber.

  • phone_number (string) - Phone number belonging to a subscriber. Make sure to urlencode the input.

identified_by
string (optional) Example: email

Specify your identifier, ID, phone number or email (default: email)

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "tags": [
    "Newsletter",
    1
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "BadRequest",
  "message": "Tags missing or in faulty format. "
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "SubscriberNotFound",
    "message": "Could not find subscriber"
}

{
    "error": "TagNotFound",
    "message": "Could not find tag."
}

List tags
GET/subscribers/{identifier}/tags{?identified_by}

Example URI

GET https://app.rule.io/api/v2/subscribers/[email protected]/tags?identified_by=email
URI Parameters
HideShow
identifier
enum (required) Example: [email protected]
  • id (number) - ID belonging to a subscriber.

  • email (string) - Email belonging to a subscriber.

  • phone_number (string) - Phone number belonging to a subscriber. Make sure to urlencode the input.

identified_by
string (optional) Example: email

Specify your identifier, ID, phone number or email (default: email)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "tags": [
    {
      "id": 1,
      "name": "Newsletter"
    },
    {
      "id": 2,
      "name": "Customers"
    }
  ]
}

Delete subscriber tag

Delete subscriber tag
DELETE/subscribers/{identifier}/tags/{tag_identifier}{?identified_by}

Example URI

DELETE https://app.rule.io/api/v2/subscribers/[email protected]/tags/1?identified_by=email
URI Parameters
HideShow
identifier
enum (required) Example: [email protected]
  • id (number) - ID belonging to a subscriber.

  • email (string) - Email belonging to a subscriber.

  • phone_number (string) - Phone number belonging to a subscriber. Make sure to urlencode the input.

tag_identifier
enum (required) Example: 1
  • id (number) - ID belonging to a tag.

  • name (string) - Name belonging to a tag. Be sure to urlencode names with spaces.

identified_by
string (optional) Example: email

Specify your identifier, ID, phone number or email (default: email)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "TagNotFound",
    "message": "Could not find tag."
}

{
    "error": "SubscriberNotFound",
    "message": "Could not find subscriber."
}

Transactions

Resources related to sending transactions

Send transaction

Send transaction
POST/transactionals

Sending text message transactions comes with an additional fee of 0.40 SEK per sent text message.

Example URI

POST https://app.rule.io/api/v2/transactionals
Request  email transaction
HideShow
Headers
Content-Type: application/json
Body
{
  "transaction_type": "email",
  "transaction_name": "Password reset",
  "subject": "Password reset",
  "from": {
    "name": "Rule",
    "email": "[email protected]"
  },
  "to": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "content": {
    "plain": "UGFzc3dvcmQgcmVzZXQ=",
    "html": "PHA+UGFzc3dvcmQgcmVzZXQ8L3A+"
  }
}
Request  email with template transaction
HideShow
Headers
Content-Type: application/json
Body
{
  "transaction_type": "email",
  "transaction_name": "Password reset",
  "template_id": 1,
  "subject": "Password reset",
  "from": {
    "name": "Rule",
    "email": "[email protected]"
  },
  "to": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "content": [
    {
      "block_id": "one_column",
      "block_content": [
        {
          "title": "Title number one",
          "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
          "image": "http://example.com/one.jpg",
          "url": "http://example.com/one"
        }
      ]
    }
  ]
}
Request  text message transaction
HideShow
Headers
Content-Type: application/json
Body
{
  "transaction_type": "text_message",
  "from": {
    "name": "Rule"
  },
  "to": {
    "phone_number": "+46123456789"
  },
  "content": "Hello, world!"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "transaction_id": 1
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "BadTransactionType",
    "message": "Valid transaction types are email or text_message."
}

{
    "error": "ValidationError",
    "message": [
        {
            "from.email": ["Attribute is required."]
        }
    ]
}

{
    "error": "SuppressedSubscriber",
    "message": "Subscriber is suppressed and will not receive email transactions."
}

{
    "error": "InactiveSubscriber",
    "message": "Subscriber has not opted in and will not receive email transactions."
}

Templates

Get templates

Get templates
GET/templates

Example URI

GET https://app.rule.io/api/v2/templates
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "templates": [
    {
      "id": 1,
      "name": "My template"
    },
    {
      "id": 2,
      "name": "My other template"
    }
  ]
}

Get template

Get template
GET/templates/{id}

Example URI

GET https://app.rule.io/api/v2/templates/1
URI Parameters
HideShow
id
number (required) Example: 1
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": 1,
    "name": "My template",
    "blocks": [
        "one_column",
        "two_columns"
    ],
    "content": {
        "html": "<p>Html Content</p>",
        "plain" "Plain Content"
    }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "TemplateNotFound",
  "message": "Could not find template."
}

Tags

Get tags

Get tags
GET/tags{?limit}

Example URI

GET https://app.rule.io/api/v2/tags?limit=20
URI Parameters
HideShow
limit
number (optional) Example: 20

Number of tags to fetch. Defaults to 100 and can’t exceed 100.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "tags": [
        {
            "id": 1,
            "name": "Newsletter",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00"
        },
        {
            "id": 2,
            "name": "Customers",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00"
        }
    ],
    "meta": [
        "next": "https://app.rule.io/api/v2/tags?cursor=2&limit=3&apikey=YOUR-API-KEY"
    ]
}

Delete tag

Delete tag
DELETE/tags/{identifier}

Example URI

DELETE https://app.rule.io/api/v2/tags/Newsletter
URI Parameters
HideShow
identifier
enum (required) Example: Newsletter
  • id (number) - ID belonging to a tag.

  • name (string) - Tag name. Make sure to urlencode the name.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "TagNotFound",
  "message": "Could not find tag."
}

Clear tag

Clear tag
DELETE/tags/{identifier}/clear

This action will clear all associations between the tag and its subscribers. The actual tag and subscribers will not be removed.

Example URI

DELETE https://app.rule.io/api/v2/tags/Newsletter/clear
URI Parameters
HideShow
identifier
enum (required) Example: Newsletter
  • id (number) - ID belonging to a tag.

  • name (string) - Tag name. Make sure to urlencode the name.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "TagNotFound",
  "message": "Could not find tag."
}

Subscriber fields

Create groups and fields

Create groups and fields
POST/customizations

  • The key attribute must have the group name and field name separated with a . E.g GroupName.FieldName

  • Valid field types are: text, single, multiple, datetime, date, time, json.

  • If no type is passed in the request, the field will default to the text field type.

Example URI

POST https://app.rule.io/api/v2/customizations
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "fields": [
    {
      "key": "Address.Street",
      "type": "text"
    },
    {
      "key": "Order.Created",
      "type": "datetime"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "BadRequest",
    "message": "Fields missing or in wrong format."
}

{
    "error": "BadRequest",
    "message": "Filed type {type} is not allowed"
}

{
    "error": "ReservedKeyword",
    "message": "Field name: {name} is a reserved keyword."
}

{
    "error": "BadRequest",
    "message": "Key: {key} is formatted incorrectly"
}

Get groups with fields

Get groups
GET/customizations{?limit}

Example URI

GET https://app.rule.io/api/v2/customizations?limit=20
URI Parameters
HideShow
limit
number (optional) Example: 20

Number of items to fetch. Defaults to 100 and can’t exceed 100.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "groups": [
        {
            "id": 1,
            "name": "Address",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00",
            "fields": [
                {
                    "id": 1,
                    "name": "Street",
                    "type": "text"
                }
            ]
        },
        {
            "id": 2,
            "name": "Order",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00",
            "fields": [
                {
                    "id": 2,
                    "name": "Created",
                    "type": "datetime"
                }
            ]
        }
    ],
    "meta": [
        "next": "https://app.rule.io/api/v2/customizations?cursor=2&limit=3&apikey=YOUR-API-KEY"
    ]
}

Get group with fields

Get group
GET/customizations/{identifier}

Example URI

GET https://app.rule.io/api/v2/customizations/1
URI Parameters
HideShow
identifier
enum (required) Example: 1
  • id (number) - ID belonging to a group.

  • name (string) - Group name. Make sure to urlencode the name.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "name": "Address",
  "created_at": "2016-03-29 12:00:00",
  "updated_at": "2016-03-29 12:00:00",
  "fields": [
    {
      "id": 1,
      "name": "Street",
      "type": "text"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "NotFound",
  "message": "Could not find group."
}

Suppressions

suppressions

Register suppression
POST/suppressions

You can suppress subscribers by specifying dispatchers and message types. If you want to suppress the subscriber on everything, simply omitt the suppress_on attribute.

  • Valid dispatcher types are: campaign and transaction.

  • Valid message types are: text_message and email.

Example URI

POST https://app.rule.io/api/v2/suppressions
Request  total
HideShow
Headers
Content-Type: application/json
Body
{
  "subscribers": [
    {
      "email": "[email protected]"
    },
    {
      "phone_number": "+46123456789"
    },
    {
      "id": 1
    }
  ]
}
Request  specified
HideShow
Headers
Content-Type: application/json
Body
{
  "subscribers": [
    {
      "email": "[email protected]"
    },
    {
      "phone_number": "+46123456789"
    },
    {
      "id": 1
    }
  ],
  "suppress_on": {
    "campaign": [
      "email",
      "text_message"
    ],
    "transaction": [
      "email"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "SubscriberNotFound",
  "message": "Could not find subscriber."
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "BadRequest",
    "message": "Subscribers missing or in invalid format."
}

{
    "error": "InvalidIdentifier",
    "message": "Identifier: :identifier is not a valid identifier.",
    "valid_identifiers": ["email", "phone_number", "id"]
}        

{
    "error": "InvalidDispatcherType",
    "message": "An invalid dispatcher type was detected.",
    "valid_dispatcher_types": ["campaign", "transaction"]
}

{
    "error": "InvalidMessageType",
    "message": "An invalid message type was detected.",
    "valid_message_types": ["email", "text_message"]
}

Get suppressions

Get suppressions
GET/suppressions{?limit}

Example URI

GET https://app.rule.io/api/v2/suppressions?limit=20
URI Parameters
HideShow
limit
number (optional) Example: 20

Number of items to fetch. Defaults to 100 and can’t exceed 100.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "suppressions": [
        {
            "id": 1,
            "created_at": "2016-04-02 12:00:00",
            "dispatcher_type": "campaign",
            "message_type": "email",
            "suppressed_source_type": "bounce",
            "subscriber": {
                "id": 1,
                "email": "[email protected]" ,
                "phone_number": "+46123456789"
            }
        },
        {
            "id": 2,
            "created_at": "2016-04-02 12:00:00",
            "dispatcher_type": "transactional",
            "message_type": "text_message",
            "suppressed_source_type": "user",
            "subscriber": {
                "id": 2,
                "email": "[email protected]" ,
                "phone_number": "+46123456987"
            }
        }
    ],
    "meta": {
        "next": "https://app.rule.io/api/v2/suppressions?cursor=2&limit=3&apikey=YOUR-API-KEY"
    }
    ]
}

Campaigns

Campaigns

Get campaigns
GET/campaigns{?limit}

Example URI

GET https://app.rule.io/api/v2/campaigns?limit=20
URI Parameters
HideShow
limit
number (optional) Example: 20

Number of items to fetch. Defaults to 100 and can’t exceed 100.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "campaigns": [
    {
      "id": 1,
      "name": "My campaign",
      "created_at": "2016-04-05 12:00:00",
      "status": "draft",
      "type": "email"
    },
    {
      "id": 2,
      "name": "My other campaign",
      "created_at": "2016-04-05 12:00:00",
      "status": "sent",
      "type": "text_message"
    }
  ],
  "meta": {
    "next": "https://app.rule.io/api/v2/campaigns?cursor=2&limit=3&apikey=YOUR-API-KEY"
  }
}

Campaigns

Create campaign
POST/campaigns

  • Valid message types are: email and text_message.

  • email_template_id is optional.

  • For email campaigns, both plain and html content must be based64 encoded.

  • When passing the negative attribute along a tag/segment it will not send send the message to members contained in that tag/segment.

Example URI

POST https://app.rule.io/api/v2/campaigns
Request  create
HideShow
Headers
Content-Type: application/json
Body
{
  "subject": "My subject",
  "from": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "email_template_id": 1,
  "message_type": "email",
  "language": "sv",
  "recipients": {
    "tags": [
      {
        "identifier": "Newsletter"
      }
    ],
    "segments": [
      {
        "identifier": "Stockholm",
        "negative": true
      }
    ]
  },
  "content": {
    "plain": "UGFzc3dvcmQgcmVzZXQ=",
    "html": "PHA+UGFzc3dvcmQgcmVzZXQ8L3A+"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "name": "My campaign",
  "email_template_id": 1,
  "created_at": "2016-04-05 12:00:00",
  "status": "draft",
  "type": "email",
  "recipients": {
    "tags": [
      {
        "id": 1,
        "name": "Newsletter",
        "negative": false
      }
    ],
    "segments": [
      {
        "id": 1,
        "name": "Stockholm",
        "negative": true
      }
    ],
    "subscribers": []
  }
}

Get campaign

Get campaign
GET/campaigns/{id}

Example URI

GET https://app.rule.io/api/v2/campaigns/1
URI Parameters
HideShow
id
number (required) Example: 1
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "name": "My campaign",
  "created_at": "2016-04-05 12:00:00",
  "status": "sent",
  "type": "email",
  "recipients": {
    "tags": [
      {
        "id": 1,
        "name": "Newsletter",
        "negative": false
      }
    ],
    "segments": [
      {
        "id": 1,
        "name": "Stockholm",
        "negative": true
      }
    ],
    "subscribers": [
      {
        "id": 1,
        "email": "[email protected]",
        "phone_number": "+46123456789"
      }
    ]
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "CampaignNotFound",
  "message": "Could not find campaign."
}

Get statistics

Statistics overview
GET/campaigns/{id}/statistics

Example URI

GET https://app.rule.io/api/v2/campaigns/1/statistics
URI Parameters
HideShow
id
number (required) Example: 1
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "sent": 10,
    "name": "My campaign",
    "sent_at" "2016-09-26 12:00:00",
    "open": {
        "unique": 1,
        "total": 5
    },
    "click": {
        "unique": 1,
        "total": 5
    },
    "browser": {
        "unique": 1,
        "total": 5
    },
    "bounced": {
        "hard": 1,
        "soft": 5
    },
    "unsubscribed": {
        "user": 1,
        "spam": 5
    }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "CampaignNotFound",
  "message": "Could not find campaign."
}

Send campaign

  • Valid message types are: email and text_message.

  • For email campaigns, both plain and html content must be based64 encoded.

  • When passing the negative attribute along a tag/segment it will not send send the message to members contained in that tag/segment.

Sending text message campaigns comes with an additional fee of 0.40 SEK per sent text message.

Send campaign
POST/campaigns/send

Example URI

POST https://app.rule.io/api/v2/campaigns/send
Request  email campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "subject": "My subject",
  "from": {
    "email": "[email protected]",
    "name": "Rule"
  },
  "message_type": "email",
  "language": "sv",
  "recipients": {
    "tags": [
      {
        "identifier": "My tag"
      }
    ],
    "segments": [
      {
        "identifier": "My segment",
        "negative": true
      }
    ]
  },
  "content": {
    "plain": "UGFzc3dvcmQgcmVzZXQ=",
    "html": "PHA+UGFzc3dvcmQgcmVzZXQ8L3A+"
  }
}
Request  text message campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "subject": "My subject",
  "from": {
    "email": "[email protected]",
    "name": "Rule"
  },
  "message_type": "text_message",
  "language": "sv",
  "recipients": {
    "tags": [
      {
        "identifier": "My tag"
      }
    ],
    "segments": [
      {
        "identifier": "My segment",
        "negative": true
      }
    ]
  },
  "content": "My content"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "TemplateNotFound",
  "message": "Could not find email template."
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "ValidationError",
  "message": {
    "subject": [
      "Attribute is required"
    ]
  }
}

Schedule campaign

  • Valid message types are: email and text_message.

  • For email campaigns, both plain and html content must be based64 encoded.

  • When passing the negative attribute along a tag/segment it will not send send the message to members contained in that tag/segment.

Sending text message campaigns comes with an additional fee of 0.40 SEK per sent text message.

Schedule campaign
POST/campaigns/schedule

Example URI

POST https://app.rule.io/api/v2/campaigns/schedule
Request  email campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "send_at": "2016-05-20 12:00:00",
  "subject": "My subject",
  "from": {
    "email": "[email protected]",
    "name": "Rule"
  },
  "message_type": "email",
  "language": "sv",
  "recipients": {
    "tags": [
      {
        "identifier": "My tag"
      }
    ],
    "segments": [
      {
        "identifier": "My segment",
        "negative": true
      }
    ]
  },
  "content": {
    "plain": "UGFzc3dvcmQgcmVzZXQ=",
    "html": "PHA+UGFzc3dvcmQgcmVzZXQ8L3A+"
  }
}
Request  text message campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "send_at": "2016-05-20 12:00:00",
  "subject": "My subject",
  "from": {
    "email": "[email protected]",
    "name": "Rule"
  },
  "message_type": "text_message",
  "language": "sv",
  "recipients": {
    "tags": [
      {
        "identifier": "My tag"
      }
    ],
    "segments": [
      {
        "identifier": "My segment",
        "negative": true
      }
    ]
  },
  "content": "My content"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "TemplateNotFound",
  "message": "Could not find email template."
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "ValidationError",
  "message": {
    "subject": [
      "Attribute is required"
    ]
  }
}

Generated by aglio on 03 Nov 2016