Smart Mailer API


Welcome to Kyvio - Smart Mailer API v1.0 This documentation is intended for experienced developers and describes how to interact with the RESTFUL Kyvio Smart mailer API. To interact with our API a user needs to have a Kyvio account and obtain their personal unique API key from their 'Account Settings' page To get your own Kyvio account go here: https://kyvio.com/pricing


HTTP/1.1 Status Codes:

  • 200 OK
  • 201 Created
  • 202 Accepted
  • 204 No Content
  • 301 Moved Permanently
  • 302 Found
  • 303 See Other
  • 304 Not Modified
  • 400 Bad Request
  • 401 Unauthorized
  • 402 Payment Required
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Allowed
  • 406 Not Acceptable
  • 408 Request Time-out
  • 409 Conflict
  • 410 Gone
  • 411 Length Required
  • 412 Precondition Failed
  • 414 Request-URI Too Large
  • 415 Unsupported Media Type
  • 416 Requested range not satisfiable
  • 500 Internal Server Error
  • 501 Not Implemented
  • 502 Bad Gateway
  • 505 HTTP Version not supported



JSON Errors (HTTP/1.1 STATUS CODES 4xx & 5xx)

{
    "success": false,
    "error": {
        "code": "1110403",
        "message": "Invalid data",
        "additionalData": [
            "{\"site_id\":[\"The selected site id is invalid.\"]}",
        ]
    },
    "dateTime": {
        "date": "2018-04-10 10:51:23.918117",
        "timezone_type": 3,
        "timezone": "UTC"
    }
}
                     

Single Response (HTTP/1.1 STATUS CODES 2xx)

{
    "success": true,
    "payload": {
        "id": 48,
        "siteId": "11",
        "subject": "subject",
        "content": "content",
        "status": 1,
        "timezone": "UTC",
    },
    "statusCode": 200,
    "dateTime": {
        "date": "2018-04-10 11:34:32.690168",
        "timezone_type": 3,
        "timezone": "UTC"
    }
}


Authentication

All request you want to send to our API must contain authentication information. For example, if your api-key is: 84fsne83yrths947r6sfgg7w4he8asdsdgsag21g1fa , then the custom authentication header should look like:

Authorization: Bearer 84fsne83yrths947r6sfgg7w4he8asdsdgsag21g1fa

You can find you api_key in your account settings



Subscriber

Class SubscriberController

  • GET

  • index

  • api/v1/subscribers

Get email subscribers list for User GET /subscribers

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • api_key
    string
    The user api key

  • POST

  • create

  • api/v1/subscribers/create

Create an email subscriber POST /subscribers/create

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • name
    string
    The name of subscriber
  • email
    string
    The email of subscriber
  • list_id
    integer
    The mailing list Id where subscriber will be added to
  • api_key
    string
    The user api key

  • GET

  • show

  • api/v1/subscribers/{id}

Get email subscriber by subscriber id GET /subscribers/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The email subscriber id
  • api_key
    string
    The user api key

  • PUT

  • update

  • api/v1/subscribers/{id}

Update the email subscriber PUT /subscribers/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of subscriber
  • name
    string
    The name of subscriber
  • email
    string
    The email of subscriber
  • list_id
    integer
    The mailing list Id where the subscriber is addedd
  • api_key
    string
    The user api key

  • DELETE

  • destroy

  • api/v1/subscribers/{id}

Delete email subscriber by subscriber id DELETE /subscribers/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The email subscriber id
  • api_key
    string
    The user api key

  • POST

  • move

  • api/v1/subscribers/{id}/move

Move email subscriber from one mailing list to another mailing list POST /subscribers/{id}/move

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • list_id_1
    integer
    The mailing list id FROM where the email subscriber will be moved
  • list_id_2
    integer
    The mailing list id where email subscriber will be moved TO
  • api_key
    string
    The user api key

  • POST

  • addToList

  • api/v1/subscribers/{id}/addtolist

Add email subscriber to a mailing list POST /subscribers/{id}/addtolist

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • list_id
    integer
    The mailing list id where email subscriber will be added
  • api_key
    string
    The user api key

  • POST

  • removeFromList

  • api/v1/subscribers/{id}/removefromlist

Remove email subscriber from mailing list POST /subscribers/{id}/removefromlist

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • list_id
    integer
    The mailing list id from where email subscriber will be removed
  • api_key
    string
    The user api key

  • GET

  • showSince

  • api/v1/subscribers/since/{date}

Get email subscribers since given date GET /subscribers/since/{date}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • date
    string
    The date in format Y-m-d H:i:s
  • api_key
    string
    The user api key

  • GET

  • showUntil

  • api/v1/subscribers/until/{date}

Get email subscribers until given date GET /subscribers/until/{date}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • date
    string
    The date in format Y-m-d H:i:s
  • api_key
    string
    The user api key

  • DELETE

  • destroySince

  • api/v1/subscribers/since/{date}

Delete email subscribers since given date DELETE /subscribers/since/{date}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • date
    string
    The date in format Y-m-d H:i:s
  • api_key
    string
    The user api key

  • DELETE

  • destroyUntil

  • api/v1/subscribers/until/{date}

Delete email subscribers until given date DELETE /subscribers/until/{date}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • date
    string
    The date in format Y-m-d H:i:s
  • api_key
    string
    The user api key

  • GET

  • showEmail

  • api/v1/subscribers/email/{email}

Get email subscriber by subscriber email GET /subscribers/email/{email}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • email
    string
    The email subscriber email address
  • api_key
    string
    The user api key

  • DELETE

  • destroyEmail

  • api/v1/subscribers/email/{email}

Delete email subscriber by subscriber email DELETE /subscribers/email/{email}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • email
    string
    The email subscriber email address
  • api_key
    string
    The user api key

  • GET

  • showList

  • api/v1/subscribers/list/{list}

Get email subscribers by mailing list GET /subscribers/list/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • list_id
    integer
    The mailing list id
  • api_key
    string
    The user api key

MailingList

Class MailingListController

  • GET

  • index

  • api/v1/mailing-list

Get all mailing lists GET /mailing-list

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • api_key
    string
    The user api key

  • POST

  • store

  • api/v1/mailing-list

Creates a new mailing list POST /mailing-list

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • name
    string
    The name of mailing list
  • from_name
    string
    The from name of mailing list
  • from_email
    string
    The from email of mailing list
  • site_name
    integer
    The mailing list will be created for the site with given name
  • api_key
    string
    The user api key

  • GET

  • show

  • api/v1/mailing-list/{id}

Get mailing list by mailing list id GET /mailing-list/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of mailing list
  • api_key
    string
    The user api key

  • PUT

  • update

  • api/v1/mailing-list/{id}

Update the mailing list PUT /mailing-list/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of mailing list
  • name
    string
    The name of mailing list
  • from_name
    string
    The from name of mailing list
  • from_email
    string
    The from email of mailing list
  • site_name
    integer
    The mailing list will be updated for the site with given name
  • api_key
    string
    The user api key

  • DELETE

  • destroy

  • api/v1/mailing-list/{id}

Delete mailing list by mailing list id DELETE /mailing-list/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of mailing list
  • api_key
    string
    The user api key

  • POST

  • cleanup

  • api/v1/mailing-list/cleanup

Cleanup mailing lists POST /mailing-list/cleanup

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • action
    string
    The action could be 'move' or 'delete'
  • condition
    string
    The condition could be 'not_opened_or_clicked' , 'not_opened' , 'not_clicked' , 'unconfirmed' , 'no_activity'
  • since
    string
    The date in format Y-m-d H:i:s
  • from_lists[]
    array
    The mailing list ids , from where must be cleanup done
  • to_lists
    integer
    The mailing list id to cleanup , required if the action is 'move'
  • api_key
    string
    The user api key

Optin

Class OptinController

  • GET

  • index

  • api/v1/optinform

Gets all email opt-in forms GET /optinform

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • api_key
    string
    The user api key

  • GET

  • show

  • api/v1/optinform/{id}

Get email opt-in form by opt-in id GET /optinform/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of email opt-in form
  • api_key
    string
    The user api key

  • DELETE

  • destroy

  • api/v1/optinform/{id}

Delete email opt-in form by opt-in id DELETE /optinform/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of email opt-in form
  • api_key
    string
    The user api key

Automation

Class AutomationController

  • GET

  • index

  • api/v1/automation/{list?}

Get all mailing lists automations GET /automation/{list}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • list
    integer
    The mailing list id , is required if needed to get the automations on some list
  • api_key
    string
    The user api key

  • POST

  • store

  • api/v1/automation

Creates a new mailing list automation POST /automation

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • mailist_id
    integer
    The id of mailing list to create an automation on
  • event_name
    string
    The event nmae of automation
  • name
    string
    The name of automation
  • action
    string
    The action of automation could be 'delete_from_all_lists' or 'delete_from_selected_lists'
  • action_values[]
    array
    The action_values of automation is array with mailing list ids,requeired only when action is NOT 'delete_from_all_lists'
  • api_key
    string
    The user api key

  • GET

  • show

  • api/v1/automation/{id}

Get mailing list automation by automation id GET /automation?id={id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of mailing list automation
  • api_key
    string
    The user api key

  • PUT

  • update

  • api/v1/automation/{id}

Update the mailing list automation by automation id PUT /automation/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of automation
  • mailist_id
    integer
    The id of mailing list to create an automation on
  • event_name
    string
    The event nmae of automation
  • name
    string
    The name of automation
  • action
    string
    The action of automation could be 'delete_from_all_lists' or 'delete_from_selected_lists'
  • action_values[]
    array
    The action_values of automation is array with mailing list ids,requeired only when action is NOT 'delete_from_all_lists'
  • api_key
    string
    The user api key

  • DELETE

  • destroyById

  • api/v1/automation/{id}

Delete mailing list automation by automation id DELETE /automation/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of automation
  • api_key
    string
    The user api key

  • DELETE

  • destroyByList

  • api/v1/automation/{list?}

Delete mailing list automation by mailing list id DELETE /automation?list={id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • list
    integer
    The mailing list id
  • api_key
    string
    The user api key

Broadcast

Class BroadcastController

  • GET

  • index

  • api/v1/broadcast

Gets all email broadcasts GET /broadcast

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • date
    string
    The datein format Y-m-d H:i:s , required if must be returned broadcasts scheduled after the date
  • api_key
    string
    The user api key

  • GET

  • index

  • api/v1/broadcast/scheduledafter/{date}

Gets all email broadcasts GET /broadcast

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • data
    string
    The datein format Y-m-d H:i:s , required if must be returned broadcasts scheduled after the date
  • api_key
    string
    The user api key

  • POST

  • store

  • api/v1/broadcast

Create a new email broadcast POST /broadcast

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • mailist_id
    integer
    The mailing list id for broadcast
  • subject
    string
    The subject of broadcast
  • content
    string
    The content of broadcast
  • schedule_type
    string
    The schedule type of broadcast , could be 'immediately' or 'scheduled_at'
  • scheduled_at
    string
    The schedule data in future , required only if scheduled_type is 'scheduled_at'
  • api_key
    string
    The user api key

  • GET

  • show

  • api/v1/broadcast/{id}

Get email broadcast by broadcast id GET /broadcast/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of broadcast
  • api_key
    string
    The user api key

  • GET

  • showRecipients

  • api/v1/broadcast/{id}/recipients

Get email broadcast recipients by broadcast id GET /broadcast/{id}/recipients

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of broadcast
  • api_key
    string
    The user api key

  • GET

  • showReport

  • api/v1/broadcast/{id}/report

Get email broadcast report by broadcast id GET /broadcast/{id}/report

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of broadcast
  • api_key
    string
    The user api key

  • GET

  • showContent

  • api/v1/broadcast/{id}/content

Get email broadcast content by broadcast id GET /broadcast/{id}/content

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of broadcast
  • api_key
    string
    The user api key

  • PUT

  • updateContent

  • api/v1/broadcast/{id}/content

Update email broadcast content by broadcast id PUT /broadcast/{id}/content

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of broadcast
  • content
    string
    The content of broadcast
  • plain_text
    string
    The plain text of broadcast
  • api_key
    string
    The user api key

  • DELETE

  • destroy

  • api/v1/broadcast/{id}

Delete email broadcast by broadcast id DELETE /broadcast/{id}

Parameters

  • PARAMETER
    TYPE
    DESCRIPTION
    VALUE
  • id
    integer
    The id of broadcast
  • api_key
    string
    The user api key