API

Overview

The Tuemilio REST API allows you to interact with your subscriber database. You can retrieve all your lists as well as all the subscriber emails.
You have full control to create, update and delete emails. Use this API as an extension of your app.
Retrieve unsubscription links, update subscription status, get regional information, delete emails, etc.

Authentication

Remember to add your URL encoded API token to all the endpoints as in the example above.

https://tuemilio.com/api/v1/lists?api_token=XXXXXXXX-XXX-XXX-XXX-XXXXXXXXXXXX

Errors

Tuemilio uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP status code summary
200
OK
Everything worked as expected.
400
Bad Request
The request was unacceptable, often due to missing a required parameter.
401
Unauthorized
No valid API key provided.
404
Not Found
The requested resource doesn't exist.
429
Too Many Requests
Too many requests hit the API too quickly.
500
Server Error
Oops! Something went wrong.

Lists

A list contains information of your page and a list of all the emails that were submitted. Lists are identified by a unique ID. An Uuid is used for building public links, such as an unsubscription link.

The list object

ATTRIBUTES
id
integer
The ID of the list to be retrieved.
name
string
The name of the list.
uuid
string
Public unique identifier of the list.
visits_count
integer
Number of visits on your site.
emails_count
integer
Number of emails collected.
unique_visits
integer
Number of unique visits on your site.
conversion
decimal unitary
Percentage of unique visitors that left an email.
last_activity
string
UTC time when last email was submitted.
list
A list of email objects that were submitted.
webhook
object
Webhook object belonging to the list.
email_notification
object
Email notification object belonging to the list.

Example Response

{
    "id":2, 
    "name": "Landing",
    "uuid": "5a88c002-ed6d-5302-a78b-ae8355715996",
    "visits_count": 11,
    "emails_count": 2,
    "unique_visits": 1,
    "conversion": 2,
    "last_activity": "2018-06-19 10:47:20",
    "emails": [

    ],
    "webhook": {
        "url": "https://yourapp.com/webhook",
        "enabled": 1,
        "last_ping": "2018-05-04 14:30:46",
        "created_At": "2018-05-03 21:20:33"
    },
    "email_notification": {
        "address": "hello@hello.com",
        "every": 5,
        "enabled": 1,
        "last_sent": null,
        "created_at": "2018-05-04 14:30:24"
    }
}
        

List all lists

Returns a list of lists you’ve previously created. The lists are returned in sorted order, with the most recent list appearing first.

ARGUMENTS
No arguments.

Returns

Returns an array of lists. Each entry in the array is a separate charge object. If no lists are available, the resulting array will be empty.

Definition

GET https://tuemilio.com/api/v1/lists

Example Request

$ curl https://tuemilio.com/api/v1/lists?api_token=XXXXXXXX

Example Response

[
    {
        "id":2, 
        "name": "Landing",
        "uuid": "5a88c002-ed6d-5302-a78b-ae8355715996",
        "visits_count": 11,
        "emails_count": 2,
        "unique_visits": 1,
        "conversion": 2,
        "last_activity": "2018-06-19 10:47:20",
        "emails": [

        ],
        "webhook": {
            "url": "https://yourapp.com/webhook",
            "enabled": 1,
            "last_ping": "2018-05-04 14:30:46",
            "created_At": "2018-05-03 21:20:33"
        },
        "email_notification": {
            "address": "hello@hello.com",
            "every": 5,
            "enabled": 1,
            "last_sent": null,
            "created_at": "2018-05-04 14:30:24"
        }
    },
    {...},
    {...}
]
        

Retrive a list

Retrieves the details of an existing lsit. You need only supply the customer id that was returned upon list creation.

ARGUMENTS
id
REQUIRED
The identifier of the list to be retrieved.

Returns

Returns a list if a valid identifier was provided, and throws an error otherwise.

Definition

GET https://tuemilio.com/api/v1/lists/{id}

Example Request

$ curl https://tuemilio.com/api/v1/lists/152?api_token=XXXXXXXX

Example Response

{   
    "id": 2, 
    "name": "Landing", 
    "uuid": "5a88c002-ed6d-5302-a78b-ae8355715996", 
    "emails_count": 2, 
    "visits_count": 11, 
    "unique_visits": 1, 
    "conversion": 2, 
    "last_activity": "2018-06-19 10:47:20", 
    "emails": [ 

    ], 
    "webhook": {
        "url": "https://yourapp.com/webhook",
        "enabled": 1,
        "last_ping": "2018-05-04 14:30:46",
        "created_At": "2018-05-03 21:20:33"
    },
    "email_notification": {
        "address": "hello@hello.com",
        "every": 5,
        "enabled": 1,
        "last_sent": null,
        "created_at": "2018-05-04 14:30:24"
    }
}
        

Emails

An email contains information of your subscribers.

The email object

ATTRIBUTES
id
integer
The ID of the email.
address
string
The subscribed email address.
ip
string
The subscriber's ip where the email was submitted.
origin_url
string
The url from where the email where submitted.
referrer_url
string
The url where the user found your site.
subscribed
boolean
States if the subscriber is subscribed.
cookie_uuid
string
Cookie uuid stored in subscriber browser.
uuid
string
Public unique identifier of the email.
click_time
string
Time the subscriber took to subscribe in seconds.
created_at
string
Date and time of subscribtion.
location
object
Location object belonging to the email.
continent_code
string
Continent code of subscriber location.
continent
string
Continent name of subscriber location.
country_code
string
Country code of subscriber location.
country
string
Country of subscriber location.
latitude
string
Latitude of subscriber location.
longitude
string
Longitude of subscriber location.
language
string
Language spoken in subscriber's country.
language_code
string
Language code spoken in subscriber's country.
city
string
City of subscriber location.
timezone
string
Timezone of subscriber location.
region
string
Region of subscriber location.
zip
string
Zip code of subscriber location.
subscriber
object
Subscriber object belonging to the email.
language
string
Preferred language by the subscriber.
language_code
string
Preferred language code by the subscriber.

Example Response

{ 
  "id": 1234, 
  "address": "hello@company.com", 
  "ip": "XXX.XX.XX.X", 
  "subscribed": 1, 
  "click_time": "140",  
  "referrer_url": "https://www.producthunt.com/",
  "origin_url": "https://www.yourapp.com/",
  "unsubscribe_link": "https://tuemilio.com/email/941c10d6-a8bb-5d4d-880b-69fdef36fabe/unsubscribe"
  "created_at": "2018-05-03 18:50:57",
  "location": {
    "continent_code": "OC", 
    "continent": "Oceania", 
    "country_code": "AU", 
    "country": "Australia", 
    "region_code": "NSW", 
    "latitude": "-33.903200", 
    "longitude": "150.967700", 
    "language": "English", 
    "language_code": "en", 
    "city": "Sydney", 
    "timezone": "7", 
    "region": "New South Wales", 
    "zip": 2012, 
  },
  "subscriber": {
    "language": "English",
    "language_code": "en"
  }
}
              

List all emails of a list

You can see a list of emails belonging to a specific list. The emails are returned in sorted order, with the most recent emails appearing first.

ARGUMENTS
id
REQUIRED
The ID of the list whose emails will be retrieved.

Returns

Returns all emails in a list if a valid identifier was provided, and throws an error otherwise.

Definition

GET https://tuemilio.com/api/v1/lists/{LIST_ID}/emails

Example Request

$ curl https://tuemilio.com/api/v1/lists/{LIST_ID}/emails?api_token=XXXXXXXX

Example Response

[ 
  { 
    "id": 1, 
    "address": "hello@company.com", 
    "ip": "127.0.0.1", 
    "origin_url": null, 
    "referrer_url": "Direct", 
    "subscribed": 1, 
    "click_time": "140",  
    "created_at": "2018-05-03 18:50:57",
    "location": {
      "continent_code": null, 
      "continent": null, 
      "country_code": null, 
      "country": null, 
      "region_code": null, 
      "latitude": null, 
      "longitude": null, 
      "language": "Unknown", 
      "language_code": null, 
      "city": null, 
      "timezone": "", 
      "region": null, 
      "zip": null, 
    },
      "subscriber": {
      "language": "English",
      "language_code": "en"
    }
  }, 
  {...},
  {...}  
]
            

Retrieve an email from a list

Get an email object from a list.

ARGUMENTS
id
REQUIRED
The ID of the list whose email will be retrieved.
id
REQUIRED
The ID of the email that will be retrieved.

Returns

Returns an email object if a valid identifier was provided, and throws an error otherwise.

Definition

GET https://tuemilio.com/api/v1/lists/{LIST_ID}/emails/{EMAIL_ID}

Example Request

$ curl https://tuemilio.com/api/v1/lists/{LIST_ID}/emails/{EMAIL_ID}?api_token=XXXXXXXX

Example Response

{ 
  "id": 1, 
  "address": "hello@company.com", 
  "ip": "127.0.0.1", 
  "origin_url": null, 
  "referrer_url": "Direct", 
  "subscribed": 1, 
  "click_time": "140",  
  "created_at": "2018-05-03 18:50:57",
  "location": {
    "continent_code": null, 
    "continent": null, 
    "country_code": null, 
    "country": null, 
    "region_code": null, 
    "latitude": null, 
    "longitude": null, 
    "language": "Unknown", 
    "language_code": null, 
    "city": null, 
    "timezone": "", 
    "region": null, 
    "zip": null, 
  },
  "subscriber": {
    "language": "English",
    "language_code": "en"
  }
}
            

Create an email in a list.

Add a new email to a especific list.

ARGUMENTS
id
REQUIRED
The ID of the list where an email will be added.
address
REQUIRED
The email address to be added.
ip
optional
The ip of the subscriber.

Returns

Returns the created email object, and throws an error otherwise.

Definition

POST https://tuemilio.com/api/v1/lists/{LIST_ID}/emails

Example Request

$ curl https://tuemilio.com/api/v1/lists/{LIST_ID}/emails?api_token=XXXXXXXX

Example Response

{ 
  "id": 1, 
  "address": "hello@company.com", 
  "ip": "127.0.0.1", 
  "origin_url": null, 
  "referrer_url": "Direct", 
  "subscribed": 1, 
  "click_time": "140",  
  "created_at": "2018-05-03 18:50:57",
  "location": {
    "continent_code": null, 
    "continent": null, 
    "country_code": null, 
    "country": null, 
    "region_code": null, 
    "latitude": null, 
    "longitude": null, 
    "language": "Unknown", 
    "language_code": null, 
    "city": null, 
    "timezone": "", 
    "region": null, 
    "zip": null, 
  },
  "subscriber": {
    "language": "English",
    "language_code": "en"
  }
}
            

Update an email in a list.

Update an email of an especific list.

ARGUMENTS
id
REQUIRED
The ID of the list where the email is stored.
id
REQUIRED
The ID of the email to be updated.
address
optional
The email address to be updated.
subscribed
optional
Boolean value of the subscription status.

Returns

Returns the updated email object, and throws an error otherwise.

Definition

POST https://tuemilio.com/api/v1/lists/{LIST_ID}/emails/{EMAIL_ID}

Example Request

$ curl https://tuemilio.com/api/v1/lists/{LIST_ID}/emails/{EMAIL_ID}?api_token=XXXXXXXX

Example Response

{ 
  "id": 1, 
  "address": "hello@company.com", 
  "ip": "127.0.0.1", 
  "origin_url": null, 
  "referrer_url": "Direct", 
  "subscribed": 1, 
  "click_time": "140",  
  "created_at": "2018-05-03 18:50:57",
  "location": {
    "continent_code": null, 
    "continent": null, 
    "country_code": null, 
    "country": null, 
    "region_code": null, 
    "latitude": null, 
    "longitude": null, 
    "language": "Unknown", 
    "language_code": null, 
    "city": null, 
    "timezone": "", 
    "region": null, 
    "zip": null, 
  },
  "subscriber": {
    "language": "English",
    "language_code": "en"
  }
}
            

Delete an email in a list.

Delete an email from an especific list.

ARGUMENTS
id
REQUIRED
The ID of the list from where the email will be deleted.
id
REQUIRED
The ID of the email to be deleted.

Returns

Returns a //TODO, and throws an error otherwise.

Definition

DELETE https://tuemilio.com/api/v1/lists/{LIST_ID}/emails/{EMAIL_ID}

Example Request

$ curl https://tuemilio.com/api/v1/lists/{LIST_ID}/emails?api_token=XXXXXXXX
                -X DELETE
              

Example Response

{ 
  "id": 1, 
  "address": "hello@company.com", 
  "ip": "127.0.0.1", 
  "origin_url": null, 
  "referrer_url": "Direct", 
  "subscribed": 1, 
  "click_time": "140",  
  "created_at": "2018-05-03 18:50:57",
  "location": {
    "continent_code": null, 
    "continent": null, 
    "country_code": null, 
    "country": null, 
    "region_code": null, 
    "latitude": null, 
    "longitude": null, 
    "language": "Unknown", 
    "language_code": null, 
    "city": null, 
    "timezone": "", 
    "region": null, 
    "zip": null, 
  },
  "subscriber": {
    "language": "English",
    "language_code": "en"
  }
}
            

Public API

The public API is meant to be used in the frontend of your application. Right know the only endpoint available checks out if a certain email is on your list.
The use case for this would be to act as a gate for some features on your app.

Check email in a list

Retrieves the details of an existing lsit. You need only supply the customer id that was returned upon list creation.

ARGUMENTS
contains
REQUIRED
The email

Returns

Returns a list if a valid identifier was provided, and throws an error otherwise.

Definition

GET https://tuemilio.com/api/v1/public/lists/{list-uuid}?contains={email}

Example Request

$ curl https://tuemilio.com/api/v1/public/lists/070d1c3a-af64-584e-a055-ca9481942cba?contains=hello@gmail.com

Example Response

true
        

Webhooks

Webhooks allow you to subscribe to certain events on Tuemilio. After adding a webhook URL, we'll ping you each time a user leaves an email or unsubscribes.

POST request example

Each time you get a new subscriber we will send a post request to your app.

POST /payload HTTP/1.1
Host: localhost:4567
User-Agent: Tuemilio-Hookshot/1.0
Content-Type: application/json
X-Tuemilio-Event: new-subscriber
{
    "event": "new-subscriber",
    "data": {
        "id": 1,
        "address": "hello@company.com",
        "ip": "127.0.0.1",
        "origin_url": null,
        "referrer_url": "Direct",
        "subscribed": 1,
        "click_time": "140",
        "location": {
            "continent_code": null,
            "continent": null,
            "country_code": "blank",
            "country": null,
            "region_code": null,
            "latitude": null,
            "longitude": null,
            "language": "Unknown",
            "language_code": null,
            "city": null,
            "timezone": "",
            "region": null,
            "zip": null,
        }
        "created_at": "2018-05-03 18:50:57"
    }
}