Rule API Documentation

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]

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"
}

Encryption

Rule enforces https (TLS 1.0-1.3). Incoming http requests will result in a 3XX response, redirecting to https.

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?page=2&limit=100&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

To prevent accidental over use, the API is rate limited. This means that if you post an unusually big number of requests or generate a vast amount of error responses, any subsequent requests will not be accepted for a limited time.

An example rate limit is 2000 requests / 10 minutes and error limit 49%.

If you exceed the given limit you will receive a 429 response:

Too Many Attempts.

Along with the response some custom headers will be available:

X-RateLimit-Limit - Will show the maximum number of attempts
X-RateLimit-Remaining - Will show the number of attempts remaining
Retry-After - Will show the time until further attempts are allowed again

If you have a use case that exceeds the rate limit please contact [email protected] with a description of the use case, for further recommendation.

Testing

The Rule API is available for testing as a Postman collection:

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.
sync_subscribers - (optional) If omitted, automations are sent if there are less than 20 subscribers in the request.
fields_clear - (optional) Defaults to false if omitted. Clears all custom field data of subscriber before creating new.
tags - can consist of both names and/or ID’s of already existing tags (N.B. this means that tags consisting only of integers will be interpreted as IDs and not as text). 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']
When using the json type you have to pass in the value as json string or json in base64 format.
E.g "[{\"name\":\"Test\",\"quantity\":null,\"price\":\"100\"}]"

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.

The “field key” not allowed characters:

[] / \ | @ ^ ~ `

Length of fields data within one group should be less then 65000 characters (65 kB) (count sum of existing & new values). Please notice that special scandinavian characters are storing as two symbols.

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. One or more tag used to create the subscriber have to be tied to a sign up flow in Rule for the optin to function. Additionally, require_opt_in: true will only affect new subscriber creation, since existing subscriber are already opted in, or waiting for opt in.

Consult the Rule manual for more information about creating 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.

NOTE: Automation will be triggered only if there are less than 20 subscribers in the request.

When passing automation: "reset" or automation: "force" for a blocked subscriber, the subscriber will be set to active. Existing suppressions remain unchanged.

sync_subscribers

If omitted, automations are sent if there are less than 20 subscribers in the request.

By passing sync_subscribers: true all subscribers in the request will receive automations. Max sync limit is 100. If there are more than 100 subscribers in request - error is returned.

By passing sync_subscribers: false automations won’t be triggered for subscribers.

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.Products",
        "value": "[{\"name\":\"Product1\",\"price\":\"100\"}]",
        "type": "json"
      },
      {
        "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": "Could 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?page=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

string (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

enum (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": [],
    "syncAtSegments": [
      {
        "id": 1,
        "name": "Customers",
        "description": "New customers",
        "created_at": "2016-03-20 12:00:00",
        "updated_at": "2016-03-20 12:00:00",
        "sync_at": "12:00:00"
      }
    ]
  }
}

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

string (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

enum (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."
}

Delete subscriber ¶

Delete subscriber
DELETE`/subscribers/{identifier}{?identified_by}`

Example URI

DELETE https://app.rule.io/api/v2/subscribers/[email protected]?identified_by=email

URI Parameters

HideShow

identifier

string (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

enum (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": "NotFound",
  "message": "Could not find subscriber with given identifier."
}

Mass delete subscribers ¶

Mass delete subscribers
DELETE`/subscribers`

Attributes

identifier - Valid identifier types is email or phone_number.
identified_by - (enum) Specify your identifier email or phone number.

Example URI

DELETE https://app.rule.io/api/v2/subscribers

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "subscribers": [
    {
      "identifier": "[email protected]",
      "identified_by": "email"
    },
    {
      "identifier": "+46123456789",
      "identified_by": "phone_number"
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "Success"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "NotFound",
  "message": "Could not find subscriber with given identifier."
}

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

string (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

enum (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

string (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

enum (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"
    }
  ]
}

Subscriber clear all tags ¶

Subscriber clear all tags
DELETE`/subscribers/{identifier}/tags/clear{?identified_by}`

This action will remove subscriber from all tags. The actual tag and subscribers will not be removed.

Example URI

DELETE https://app.rule.io/api/v2/subscribers/[email protected]/tags/clear?identified_by=email

URI Parameters

HideShow

identifier

string (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

enum (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": "SubscriberNotFound",
  "message": "Could not find subscriber."
}

Delete subscriber tag ¶

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

This action will remove subscriber from the chosen tags. The actual tag and subscribers will not be removed.

Example URI

DELETE https://app.rule.io/api/v2/subscribers/[email protected]/tags/1?identified_by=email

URI Parameters

HideShow

identifier

string (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

string (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

enum (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`

Valid transaction types are: email and text_message.
For email transactions, both plain and html content must be based64 encoded.
Sending email transactions with template requires a custom template in Rule. Contact [email protected] for more information.
If you want to attach PDF file, it have size up to 50Kb and should be sent as described in the example. Field “attachment”
To see which blocks your template supports, refer to the templates section

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+"
    },
    "attachment": {
        "name": "test.pdf",
        "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL01lZGlhQm94IFswIDAgNTk1LjI4MCA4NDEuODkwXQovVHJpbUJveCBbMC4wMDAgMC4wMDAgNTk1L
    }
}

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",
            "description": "Newsletter1",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00"
        },
        {
            "id": 2,
            "name": "Customers",
            "description": "Newsletter2",
            "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?page=2&limit=3&apikey=YOUR-API-KEY"
    ]
}

Get tag ¶

Get tag
GET`/tags/{identifier}{?identified_by}{&with_count}`

Example URI

GET https://app.rule.io/api/v2/tags/Newsletter?identified_by=name&with_count=true

URI Parameters

HideShow

identifier

string (required) Example: Newsletter

id (number) - ID belonging to a tag.
name (string) - Tag name. Make sure to urlencode the name.

identified_by

enum (optional) Example: name

Specify your identifier, ID or name (default: name)

with_count

string (optional) Example: true

if it is specified, the count of subscribers would be returned.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "name": "Newsletter",
    "description": "Newsletter1",
    "recipient_count": 123,
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

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

Rename/Update tag ¶

Rename/Update tag
PUT`/tags/{identifier}`

Example URI

PUT https://app.rule.io/api/v2/tags/Newsletter

URI Parameters

HideShow

identifier

string (required) Example: Newsletter

id (number) - ID belonging to a tag.
name (string) - Tag name. Make sure to urlencode the name.

Request

HideShow

Headers

Content-Type: application/json

Body

{
    "name": "Newsletter",
    "description": "Newsletter1",

}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "name": "Newsletter",
  "description": "Newsletter1",
  "created_at": "2016-03-29 12:00:00",
  "updated_at": "2016-03-29 12:00:00"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

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

Response 409

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "DuplicateTag",
  "message": "Tag already exists."
}

Delete tag ¶

Delete tag
DELETE`/tags/{identifier}`

Example URI

DELETE https://app.rule.io/api/v2/tags/Newsletter

URI Parameters

HideShow

identifier

string (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

string (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."
}

Segments ¶

Get sync at segments ¶

Get segments
GET`/segments{?limit}`

Example URI

GET https://app.rule.io/api/v2/segments?limit=20

URI Parameters

HideShow

limit: number (optional) Example: 20
Number of segments to fetch. Defaults to 100 and can’t exceed 100.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "segments": [
        {
            "id": 1,
            "name": "Newsletter",
            "description": "Newsletter1",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00",
            "sync_at": "12:00:00"
        },
        {
            "id": 2,
            "name": "Customers",
            "description": "Newsletter2",
            "created_at": "2016-03-29 12:00:00",
            "updated_at": "2016-03-29 12:00:00",
            "sync_at": "12:00:00"
        }
    ],
    "meta": [
        "next": "https://app.rule.io/api/v2/segments?page=2&limit=2&apikey=YOUR-API-KEY"
    ]
}

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?page=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

string (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 ¶

Register 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.
- transaction - ⚠️ Ignored value
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?page=2&limit=3&apikey=YOUR-API-KEY"
    }
    ]
}

Delete suppression ¶

Delete suppression
DELETE`/suppressions/{identifier}{?identified_by}`

Example URI

DELETE https://app.rule.io/api/v2/suppressions/[email protected]?identified_by=email

URI Parameters

HideShow

identifier

string (required) Example: [email protected]

id (number) - ID belonging to a supressed subscriber.
email (string) - Email belonging to a suppression.
phone_number (string) - Phone number belonging to a suppression. Make sure to urlencode the input.

identified_by

enum (optional) Example: email

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

dispatcher_type

enum (optional) Example: campaign

Delete specific type, see valid list of types in POST

message_type

enum (optional) Example: email

Delete specific type, see valid list of types in POST

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."
}

Campaigns ¶

Get campaigns
GET`/campaigns{?limit}{&type}{&created_from}{&created_to}{&sent_from}{&sent_to}`

Example URI

GET https://app.rule.io/api/v2/campaigns?limit=20&type=1&created_from=2024-05-05&created_to=2024-06-05&sent_from=2024-05-05&sent_to=2024-06-05

URI Parameters

HideShow

limit: number (optional) Example: 20
Number of items to fetch. Defaults to 100 and can’t exceed 100.
type: number (optional) Example: 1
Message type of campaign. Email - 1, SMS - 2.
created_from: string (optional) Example: 2024-05-05
To get campaigns created from date.
created_to: string (optional) Example: 2024-06-05
To get campaigns created to date.
sent_from: string (optional) Example: 2024-05-05
To get campaigns sent from date.
sent_to: string (optional) Example: 2024-06-05
To get campaigns sent to date.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "campaigns": [
        {
            "id": 1,
            "name": "My campaign",
    "sent_at" "2016-09-26 12:00:00",
            "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?page=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",
"sent_at" "2016-09-26 12:00:00",
    "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
    "campaign_id": 1
}

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"
    ]
  }
}

Delete campaign ¶

Delete campaign
DELETE`/campaign/{id}`

Example URI

DELETE https://app.rule.io/api/v2/campaign/1

URI Parameters

HideShow

id

string (required) Example: 1

id (number) - ID belonging to a campaign.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "Success"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "CampaignNotFound",
  "message": "Could not find campaign."
}

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,
  "campaign_id": 1
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "ValidationError",
  "message": {
    "subject": [
      "Attribute is required"
    ]
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "TemplateNotFound",
  "message": "Could not find email template."
}

Webhooks ¶

    Webhooks are not part of the REST API but a way for you to get a request to an endpoint of your choice, triggered by an event in Rule.

    Webhooks can be setup in your Rule account and more info about web hooks can be found here.

    Below you see the data payload in the response from the respective web hook.

Transactions

Transaction was sent:

{
      "message": {
          "id": 111111,
          "transaction_id": 111111,
          "subject": "dummy-subject",
          "type": "email/text_message",
          "created_at": "1970-01-01 00:00:00"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      }
  }

Transaction link was clicked

{
      "transaction": {
          "id": 111111,
          "name": "transaction-name",
          "message_type": "email/text_message"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      },
      "link": "https://www.example.com"
  }

Transaction was opened

{
      "transaction": {
          "id": 111111,
          "name": "transaction-name",
          "message_type": "email/text_message"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      }
  }

Campaigns

Campaign was sent:

{
      "campaign": {
              "id": 111111,
              "name": "campaign-name",
              "message_type": "email/text_message",
              "number_of_recipients": 123,
              "total_sent": 123
        }
  }

Campaign link was clicked

{
      "campaign": {
          "id": 111111,
          "name": "campaign-name",
          "message_type": "email/text_message"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      },
      "link": "https://www.example.com"
  }

Campaign was opened

{
      "campaign": {
          "id": 111111,
          "name": "campaign-name",
          "message_type": "email/text_message"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      }
  }

Subscribers

Subscriber was opted in:

{
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      }
  }

Subscriber was suppressed:

{
        "dispatcher_type": "campaign/transactional",
        "message_type": "email/text_message",
        "suppressed_source_type": "user/admin/spam/api",
        "subscriber": {
              "id": 111111,
              "email": "[email protected]",
              "phone_number": "+46705555555"
        },
        "account": {
              "name": "account-name"
        }
  }

Subscriber was removed from tag:

{
        "tag": {
              "id": 111111,
              "name": "tag-name"
        },
        "subscriber": {
              "id": 111111,
              "email": "[email protected]",
              "phone_number": "+46705555555"
        }
  }

Subscriber was added to tag:

{
        "tag": {
              "id": 111111,
              "name": "tag-name"
        },
        "subscriber": {
              "id": 111111,
              "email": "[email protected]",
              "phone_number": "+46705555555"
        }
  }

Subscriber was added to filter:

{
      "segment": {
          "id": 111111,
          "name": "segment-name"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555",
          "account": {
              "id": "account-id",
              "name": "account-name"
          }
      }
  }

Subscriber was bounced:

{
        "bounce": {
              "dispatcher_id": 111111,
              "type": "soft/hard",
              "message_type": "email",
              "dispatcher_type": "campaign",
              "bounce_message": "bounce message"
        },
        "subscriber": {
              "id": 111111,
              "email": "[email protected]",
              "phone_number": "+46705555555"
        },
        "account": {
              "name": "account-name"
        }
  }

Subscriber was resubscribed:

{
        "subscriber": {
              "id": 111111,
              "email": "subscriber-email",
              "phone_number": "+46705555555"
        },
        "account": {
              "name": "account-name"
        }
  }

Imports

Import was finished:

{
        "import": {
              "id": "import-id",
              "total": "import-total",
              "new": "import-new",
              "updated": "import-updated",
              "failed": "import-failed",
              "partial_failed": "import-partial-failed"
        }
  }

Preferences

Subscriber was added to preference

{
      "preferences": [
          {
              "id": 111111,
              "name": "preference-name-1"
          },
          {
              "id": 222222,
              "name": "preference-name-2"
          }
      ],
      "preference_group": {
          "id": 111111,
          "name": "preference-group-name"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      }
  }

Subscriber was removed from preference

{
      "preferences": [
          {
              "id": 111111,
              "name": "preference-name-1"
          },
          {
              "id": 222222,
              "name": "preference-name-2"
          }
      ],
      "preference_group": {
          "id": 111111,
          "name": "preference-group-name"
      },
      "subscriber": {
          "id": 111111,
          "email": "[email protected]",
          "phone_number": "+46705555555"
      }
  }

Preferences ¶

Get preference groups ¶

Get preferences groups
GET`/preference-groups`

NOTES

The field link has 2 states:
- "" - the link was changed sometime
- null - the link wasn’t set before

Example URI

GET https://app.rule.io/api/v2/preference-groups

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
{
    "id": 1,
    "account_id": 1,
    "name": "Water-group",
    "link": null,
    "preferences": [
        {
            "id": 1,
            "name": "pref1-water",
            "fallback_opt_in": false,
        },
        {
            "id": 2,
            "name": "pref2-water",
            "fallback_opt_in": false,
        }
    ]
},
{
    "id": 2,
    "account_id": 1,
    "name": "Fire-group",
    "link": "",
    "preferences": [
        {
            "id": 3,
            "name": "pref1-fire",
            "fallback_opt_in": false,
        },
        {
            "id": 4,
            "name": "pref2-fire",
            "fallback_opt_in": false,
        },
        {
            "id": 5,
            "name": "pref3-fire",
            "fallback_opt_in": false,
        }
    ]
}
]

Get preferences choices for subscriber and group ¶

Get preferences of subscriber
GET`/subscriber/{identifier}/preference_group/{preference_group_id}?identified_by=email`

Example URI

GET https://app.rule.io/api/v2/subscriber/[email protected]/preference_group/1?identified_by=email

URI Parameters

HideShow

preference_group_id

int (required) Example: 1

identifier

string (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

enum (optional) Example: email

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "preferences": [
    {
      "preference_id": 1,
      "name": "pref1-water",
      "is_opted_in": true
    },
    {
      "preference_id": 2,
      "name": "pref2-water",
      "is_opted_in": true
    }
  ]
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  {
      "error": "NotFound",
      "message": "Could not find Subscriber/PreferenceGroup with given params."
  }
}

Update state of all preferences ¶

Update preferences of subscriber
PATCH`/subscriber/{identifier}/preference_group/{preference_group_id}?identified_by=email`

Example URI

PATCH https://app.rule.io/api/v2/subscriber/[email protected]/preference_group/1?identified_by=email

URI Parameters

HideShow

preference_group_id

int (required) Example: 1

identifier

string (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

enum (optional) Example: email

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

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "preferences": [
    {
      "preference_id": 1,
      "is_opted_in": false
    },
    {
      "preference_id": 2,
      "is_opted_in": false
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "preferences": [
    {
      "preference_id": 1,
      "name": "pref1-fire",
      "is_opted_in": false
    },
    {
      "preference_id": 2,
      "name": "pref2-fire",
      "is_opted_in": false
    }
  ]
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "BadRequest",
  "message": "Some fields could not be validated",
  "fields": {
    "preferences": [
      "Required fields: preference_id, is_opted_in",
      "The is_opted_in field value must be true (1) or false (0).",
      [
        "Check fields for preferences with id: {id}"
      ]
    ]
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
    {
        "error": "NotFound",
        "message": "Could not find (Preference/PreferenceGroup/Subscriber) with given params. Check your preferences with ids: {list of preferenceIds}"
    }
}

Journeys ¶

Resources related to Journey Builder

Get journeys ¶

Get journeys
GET`/journey{?name}{?preference_id}`

Example URI

GET https://app.rule.io/api/v2/journey?name=?preference_id=

URI Parameters

HideShow

name: string (optional)
Filter journey by name.
preference_id: int (optional)
Filter journeys by ID of a preference group.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 8,
    "name": "Journey",
    "account_id": 9,
    "journey_style_id": 1,
    "sendout_time_minutes": null,
    "created_at": "2022-08-16T22:47:47.000000Z",
    "updated_at": "2022-08-16T22:47:47.000000Z",
    "sendoutConfiguration": {
      "id": 56,
      "sendTimeConfiguration": {
        "id": 8,
        "time_offset_minutes": 780
      },
      "preferenceConfiguration": {
        "id": 16,
        "preferences": [
          1
        ]
      }
    }
  }
]

Overview ¶

Authentication ¶

Encryption ¶

Pagination ¶

Error handling ¶

Rate limit ¶

Testing ¶

Subscribers ¶

Create new subscriber ¶

Create subscriberPOST/subscribers

Attributes ¶

Field types ¶

opt in ¶

automation ¶

sync_subscribers ¶

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Get subscribers ¶

Get subscribersGET/subscribers{?limit}

Example URI

Headers

Body

Get subscriber ¶

Get subscriberGET/subscribers/{identifier}{?identified_by}

Example URI

Headers

Body

Headers

Body

Get subscriber fields ¶

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

Example URI

Headers

Body

Headers

Body

Update subscriber ¶

Update subscriberPUT/subscribers/{identifier}

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Delete subscriber ¶

Delete subscriberDELETE/subscribers/{identifier}{?identified_by}

Example URI

Headers

Body

Headers

Body

Mass delete subscribers ¶

Mass delete subscribersDELETE/subscribers

Attributes ¶

Example URI

Headers

Body

Headers

Body

Headers

Body

Tags ¶

Authentication

Encryption

Pagination

Error handling

Rate limit

Testing

Create subscriber
POST`/subscribers`

Attributes

Field types

opt in

automation

sync_subscribers

Get subscribers
GET`/subscribers{?limit}`

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

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

Update subscriber
PUT`/subscribers/{identifier}`

Delete subscriber
DELETE`/subscribers/{identifier}{?identified_by}`

Mass delete subscribers
DELETE`/subscribers`

Attributes

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

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

Subscriber clear all tags
DELETE`/subscribers/{identifier}/tags/clear{?identified_by}`

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

Send transaction
POST`/transactionals`

Get templates
GET`/templates`

Get template
GET`/templates/{id}`

Get tags
GET`/tags{?limit}`

Get tag
GET`/tags/{identifier}{?identified_by}{&with_count}`