Overview

Rare.io is an email marketing platform that integrates with ecommerce platforms such as Shopify. This documentation outlines available API access.

API Endpoint

https://api4.rarelogic.com

Authentication

The API uses HTTP Basic Authentication. You can simply set the HTTP Authentication header on any request to automatically be logged in.

You will get a cookie in response that you can then use in future requests, but this is not mandatory.

Login

Request

GET /shop/{SHOP_NAME}/whoami.json
curl --user jon@rare.io:mypwd https://api4.rarelogic.com/shop/rarelogic-test/whoami.json -v -H "Accept: application/json"
* Connected to api4.rarelogic.com (52.71.158.9) port 443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: api4.rarelogic.com
* Server certificate: Let's Encrypt Authority X3
* Server certificate: DST Root CA X3
* Server auth using Basic with user 'jon@rare.io'
> GET /shop/rarelogic-test/whoami.json HTTP/1.1
> Host: api4.rarelogic.com
> Authorization: Basic am9uQHJhcmUuaW86ZGVycA==
> User-Agent: curl/7.49.1
> Accept: application/json
  

Response


< HTTP/1.1 200 OK
< Server: nginx/1.10.1
< Date: Thu, 16 Feb 2017 20:33:38 GMT
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< X-Frame-Options: ALLOWALL
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< ETag: W/"99a0af7ef0f80cf46aef8d40c4c5d83e"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _admin_session=RjJIYkg0MlYrRDNxL1c0aXdqT3hldDkrazMxeklHQXNPOFBMVGYzcnE2WEV2OGlUQ0hqbGRKZW5xU2ZZSlBRTVpobHFuUml2T3NpNEt1RnVUbnhtM3E2Q2k3alB6TTE5MEc4MCs2akRuQVBKZkZXd254VkNKSFQvY0Y0YXNkZXZwb1o2WHl1UmY5K1M2RGJnelc0eVJjbTU3eml4TzltTHluNCtSeEpJNGVPU1FpNjV3NFI2c01wSnhqTE4xaFJULS0wZFg5ZDRJa3BBMlZxM2FqcXF2c3VBPT0%3D--5e1deb68bbd98c7dadd5d0d5c568769c35d83491; path=/; HttpOnly
< X-Request-Id: 2e4d10f6-70c8-4d8a-934d-bcf4d7cc05c5
< X-Runtime: 0.084319
< Vary: Origin
< X-SERVER-HOSTNAME: api02
< X-Proxy-Cache: MISS
<
* Connection #0 to host api4.rarelogic.com left intact
{"user":{"email":"jon@rare.io","shop_name":"rarelogic-test","city":null,"street":null,"region":null,"country":null,"postal":null,"phone":null,"currently_etling":false,"initial_etl":true,"mailer_import_active":false,"ecommerce_import_active":false,"delinquent":false}}

Logout

To subscribe to a shop's mailouts, you'll need the shop username, a customer email, and the customer's name

Request

GET /logout

Subscriptions

This endpoint does not require authentication as it is meant to be embedded in public facing websites that allow email collection.

Subscribe

Add a contact to your account.

Request

POST /shop/{SHOP_NAME}/subscribe.json?noredirect=1
Property Required Requirements Description
customer_email Yes Valid email address Recipient email address.
firstname No String Recipient first name.
lastname No String Recipient last name.
fullname No String Recipient fullname.

Unsubscribe

Set a contact to unsubscribed from your account or remove the subscriber from a specific list.

Request

POST /shop/{SHOP_NAME}/unsubscribe.json?noredirect=1
Property Required Requirements Description
customer_email Yes Valid email address Recipient email address.
list_id No Valid list id Customer list id.

Customers API

This endpoint is used for managing customer contacts.

Get Customers

Returns a paginated list of contacts in your account.

Request

GET /shop/{SHOP_NAME}/customers.json
Property Required Requirements Description
page No Integer Current page.
per No Integer Results per page.

Get Customer

Get a customer's record including their product recommendations.

Request

GET /shop/{SHOP_NAME}/customers/{CUSTOMER_EMAIL}.json

Response

{
"id":"jon@rare.io",
"created_at":"2017-02-11T11:24:47.150+00:00",
"updated_at":"2017-10-06T14:16:03.252+00:00",
"email":"jon@rare.io",
"fullname":"Jon Rare",
"accepts_email":true,
"city":"ottawa",
"country":"canada",
"purchases":[
  {"id":"5372458691","name":"Pivot Star Sweatshirt","product_id":"5372458691"},
  {"id":"5373054979","name":"Comic explosion pants","product_id":"5373054979"},
  {"id":"5373086851","name":"Talk Derby To Me Sticker","product_id":"5373086851"},
  {"id":"10087894734","name":"IS THIS A DRAFT PRODUCT","product_id":"10087894734"}
],
"predictions":[
  {"id":"2005203651","name":"Free item","product_id":"2005203651"},
  {"id":"2005209923","name":"Gift card","product_id":"2005209923"},
  {"id":"360589851","name":"RareLogic Inc.","product_id":"360589851"},
  {"id":"3659200451","name":"Roller Derby Sticker","product_id":"3659200451"}
]
"connector_name":"shopify","connector_id":{"n":293974675057214637552692523357105922592},
"source":"csv import",
"tags":["vip customer"],
"member_lists":[{"list_id":"73c00286-5e43-11e6-901f-13b3013f72bf"}]
}

Update Customer

Update a customer's properties.

Request

PUT /shop/{SHOP_NAME}/customers/{CUSTOMER_EMAIL}.json
Property Required Requirements Description
customer_email Yes Valid email address Customer email
firstname No String Customer first name
lastname No String Customer last name
fullname No String Customer fullname
tags No Array Array of tags, ie: ["canada", "vip"]

Remove Customer

Permanently deletes a customer in your account. Customers with 1 order or more cannot be deleted.

Request

DELETE /shop/{SHOP_NAME}/customers/{CUSTOMER_EMAIL}

Lists & Segments API

This endpoint is used for managing customer lists. Contacts cant only be added or removed from simple lists not smart lists / segments.

Get Customer Lists

Returns a paginated list of both simple and smart (segments) customer lists.

Request

GET /shop/{SHOP_NAME}/customer_lists.json
Property Required Requirements Description
page No Integer Current page, ie: 1
per No Integer Results per page, ie: 25

Get List/Segment Members

Returns a paginated list of contacts within a list.

Request

GET /shop/{SHOP_NAME}/customer_lists/{CUSTOMER_LIST_ID}/subscribers.json
Property Required Requirements Description
page No Integer Current page, ie: 1
per No Integer Results per page, ie: 25

Add Contact to Simple List

Adds a contact to a specific simple list.

Request

POST /shop/{SHOP_NAME}/customer_lists/{CUSTOMER_LIST_ID}/subscribe.json?noredirect=1
Property Required Requirements Description
customer_email Yes Valid email address Customer email
firstname No String Customer first name
lastname No String Customer last name
fullname No String Customer fullname

Remove Contact from Simple List

Removes a contact from a specific simple list.

Request

DELETE /shop/{SHOP_NAME}/customer_lists/{CUSTOMER_LIST_ID}/unsubscribe.json?noredirect=1
Property Required Requirements Description
customer_email Yes Valid email address Customer email

Campaigns API

This endpoint is used for managing bulk campaign.

Get Campaigns

Returns a paginated list of campaigns.

Request

GET /shop/{SHOP_NAME}/mailouts.json?mailout_type=bulk
Property Required Requirements Description
page No Integer Current page, ie: 1
per No Integer Results per page, ie: 25

Get a Campaign

Returns a specific campaign with stats.

Request

GET /shop/{SHOP_NAME}/mailouts/{MAILOUT_ID}.json

Remove a Campaign

Deletes a campaign permanently.

Request

DELETE /shop/{SHOP_NAME}/mailouts/{MAILOUT_ID}.json

Automated Series API

This endpoint is used for managing automated series.

Get Automated Series

Returns a paginated list of series.

Request

GET /shop/{SHOP_NAME}/series.json
Property Required Requirements Description
page No Integer Current page, ie: 1
per No Integer Results per page, ie: 25

Get a Series

Returns a specific series with stats.

Request

GET /shop/{SHOP_NAME}/series/{SERIES_ID}.json

Remove a Series

Deletes a series permanently.

Request

DELETE /shop/{SHOP_NAME}/series/{SERIES_ID}.json

Coupons API

This endpoint is used for managing single-use and store coupons.

Get Coupons

Returns a paginated list of coupons.

Request

GET /shop/{SHOP_NAME}/coupons.json
Property Required Requirements Description
page No Integer Current page, ie: 1
per No Integer Results per page, ie: 25
single_use No Boolean Filter for single-use coupons only

Create a Coupon

Creates a new single-use coupon.

Request

POST /shop/{SHOP_NAME}/coupons.json
Property Required Requirements Description
coupon Yes JSON Object Coupon Object
coupon["code"] Yes String Unique coupon code, ie: COUPON12345
coupon["group_name"] No String Coupon group name, ie: abandoned cart coupons
coupon["expires"] No Datetime Coupon will no longer be used after this timestamp, ex: "2017-02-23"
coupon["enabled"] Yes Boolean Must be true
coupon["single_use"] Yes Boolean Must be true

Example Request

curl --data '{"coupon":{"code": "COUPON12345", "group_name": "abandoned cart coupons", "single_use": true, "enabled": true}}' --user jon@rare.io:mypwd https://api4.rarelogic.com/shop/rarelogic-test/coupons.json -v -H "Accept: application/json" -H "Content-Type: application/json"

Remove a Coupon

Deletes a coupon permanently.

Request

DELETE /shop/{SHOP_NAME}/coupons/{COUPON_CODE}.json