YippieMove API Tutorial and Reference

The YippieMove API allows you to integrate YippieMove into anything from customer control panels, to iPhone apps and command line utilities. This reference guide will show you how it works.

What is the YippieMove API?

The YippieMove API is a RESTful JSON based API with OAuth 2.0 based authentication[1]. This means it consists of addressable resources operated on over HTTP using standard HTTP verbs without server side sessions ('state').

The API is located at https://api.yippiemove.com/v1/.

A user of YippieMove can grant access to an API based application to create new transfer jobs, pay for them and to monitor their progress.

[1]: Like most modern JSON APIs, the YippieMove API mostly eschews HATEOAS.

Tutorial

This tutorial will show how to create a new email migration job and then monitor its progress using the API. To follow along you will need the curl command line tool. Curl will allow us to send raw HTTP requests and view the responses.

Curl is available for all major platforms and comes pre-installed on Mac OS X and most Linux installations. Windows users might be best served by installing the cygwin set of tools.

The first request: Checking What's Available

To get started, let's fire off a GET request for the root of the API.

Request:

curl -X GET "https://api.yippiemove.com/v1/"

Response:

{
    "providers": {
        "list_endpoint": "/v1/providers/"
    }
}

To read data from the API you issue a GET request. In this case the API responded with information about available endpoints in JSON format.

How do we know it's JSON, apart from what it looks like? The response headers make it clear.

Request:

curl -i -X GET "https://api.yippiemove.com/v1/"

Response:

HTTP/1.1 200 OK
Server: nginx/1.0.14
Date: Thu, 27 Sep 2012 16:19:58 GMT
...
Content-Type: application/json; charset=utf-8
...

YippieMove always returns JSON.

Making an Incorrect Request

Before we dive in further, let's quickly take a look at what happens if we do something wrong. What happens if you GET an API resource which doesn't exist?

Request:

curl -i -X GET "https://api.yippiemove.com/v1/blargh"

Response:

HTTP/1.0 404 NOT FOUND
Date: Thu, 27 Sep 2012 16:32:01 GMT
Content-Type: application/json; charset=utf-8
...

{
    "code": 404,
    "description": "Could not find the API endpoint specified.",
    "error": "Not Found"
}

Again, the YippieMove API responds in JSON. The 404 HTTP response code is returned both at the HTTP level and in the JSON content. The latter is helpful in case your client can't read HTTP response codes.

Getting a list of Providers

Let's take a look at some actual data. The response for our request to the root of the API revealed a URL to list something called providers.

Request:

curl -X GET "https://api.yippiemove.com/v1/providers/"

Response:

[
    {
        "category": "Business and Personal",
        "name": "FastMail.FM",
        "ssl": true,
        "host": "mail.messagingengine.com",
        "link": "/v1/providers/fastmail.fm",
        "identifier": "fastmail.fm",
        "port": 993
    },
    {
        "category": "Business and Personal",
        "name": "AOL",
        "ssl": false,
        "host": "imap.aol.com",
        "link": "/v1/providers/aol",
        "identifier": "aol",
        "port": 143
    },
...

The response is a list of email providers known to YippieMove. Each individual provider is shown as a dictionary with attributes.

Each YippieMove resource has a link attribute. This attribute shows the canonical URL for the resource in question or its "correct" address if you will. Let's GET one of the resources shown in the first list entry of the previous response.

Request:

curl -X GET "https://api.yippiemove.com/v1/providers/fastmail.fm"

Response:

{
    "category": "Business and Personal",
    "name": "FastMail.FM",
    "ssl": true,
    "host": "mail.messagingengine.com",
    "link": "/v1/providers/fastmail.fm",
    "identifier": "fastmail.fm",
    "port": 993
}

When you GET a specific resource the full representation of the resource is returned.

In this case we already knew the full representation because the list format contained full representations. This is not the case for most list responses. Most lists contain sparse (or "short") representations of individual resources.

Authentication

So far we didn't need to be authenticated with a YippieMove account because we accessed public API endpoints, such as providers.

To actually create a job we will need to be authenticated. This is done using the Web Server flow of OAuth 2.

Here is the high level overview of what needs to be done to authenticate:

  1. Register a new application with YippieMove.
  2. Obtain an Authorization Code for a user from YippieMove. You do this by redirecting the user to a specific page on yippiemove.com.
  3. Exchange the Authorization Code for an Access Token.
  4. Transmit the Access Token with every future request.

The sandbox

For the remainder of this tutorial we will use the YippieMove sandbox server. This server is a testing server. It acts just like the real YippieMove except it doesn't actually transfer any email and it does not charge your credit card when you buy credits. The sandbox API root URL is:

https://api.sandbox.yippiemove.com

Register an Application

Only registered applications can access YippieMove. In order to register your API application in the sandbox:

  1. Create a user account and log in.
  2. Go to your account preferences or click on your username in the upper left hand corner.
  3. Click "API client".
  4. Enter a name and click "Create client".

You will receive two pieces of information: the application key and the application secret. Never reveal the application secret to anyone as it would allow a malicious user to pretend to be your application.

For purposes of this tutorial we will use these (made up) details:

Key:    DEADBEEFDEADBEEFDEADBEEF123456
Secret: 1CE1CE1CE1CE1CE1CE1CE1CE1CE1CE

You should register your own application and use its key and secret to continue following along with this tutorial.

Obtain an Authorization Code for an Application

An application needs authorization from a user to act as that user. To ask a user to authorize your application you direct them to a specific URL in a web browser.

The URL is of this format:

https://sandbox.yippiemove.com/oauth2/authorize?redirect_uri={Redirect URL}&response_type=code&client_id={Public API Key}

For this tutorial the user should be shown this page:

https://sandbox.yippiemove.com/oauth2/authorize?redirect_uri=https%3A%2F%2Fsandbox.yippiemove.com%2Foauth2%2Fcode%2F&response_type=code&client_id=DEADBEEFDEADBEEFDEADBEEF123456

If the user is not logged in, he or she will be asked to log in. The user will be asked to grant your application access to their account.

When the user has agreed to grant your application access they will be redirected to the URL specified by the redirect_uri parameter. In order to automate the process you should redirect the user back to your own website, or if you are showing the authentication page within your app, detect when the redirect happens.

When the user is redirected, a code query parameter is added to the redirect URL. This is the Authorization Code.

In our example the user will be redirected here:

https://sandbox.yippiemove.com/oauth2/code/?code=FACEFEEDFACEFEEDFACEFEEDFACE00

We can ask the user to copy and paste the Authorization Code shown on this page, or we can just extract it from the URL. It is FACEFEEDFACEFEEDFACEFEEDFACE00 in this example.

Obtain an Access Token

Now you have an Authorization Code. You need to exchange it for an Access Token using an API call.

The API resource URL will be of this format:

https://api.sandbox.yippiemove.com/v1/oauth2/token/?code={Authorization Code}&grant_type=authorization_code&client_id={Public API Key}&redirect_uri={Redirect URL}

An HTTP basic authorization header needs to be submitted as well.

The authorization header contains the application's public key and secret key, separated by a colon. This way YippieMove knows that the request is being made by the right application since the application secret is only known to the application (remember to never reveal your application secret).

Note: Authorization Codes expire two minutes after they're generated. You must request an Access Token within this period.

Let's make the request now using curl. Remember to replace the example details with your own.

Request:

curl --user DEADBEEFDEADBEEFDEADBEEF123456:1CE1CE1CE1CE1CE1CE1CE1CE1CE1CE "https://api.sandbox.yippiemove.com/v1/oauth2/token/?code=FACEFEEDFACEFEEDFACEFEEDFACE00&grant_type=authorization_code&client_id=DEADBEEFDEADBEEFDEADBEEF123456&redirect_uri=https%3A%2F%2Fsandbox.yippiemove.com%2Foauth2%2Fcode%2F"

Response:

{
    "access_token": "FABEFABEFABEFABE",
    "token_type": "bearer",
    "expires_in": 630720000,
    "refresh_token": "1234123412341234",
    "scope": ""
}

The Access Token is found in the access_token attribute. We will use it to act on behalf of the user who granted access.

Your application have multiple access tokens from different users. Each user has the ability to at any time revoke access to your application.

Using an Access Token

Now that we have an access token we can try it. Let's see if we have access to any new API endpoints by checking the API root. To use the Access Token you specify it using a special HTTP header of this format: Authorization: Bearer {Access Token}.

Just replace FABEFABEFABEFABE with your Access Token from the previous step.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -X GET "https://api.sandbox.yippiemove.com/v1/"

Response:

{
    "users": {
        "list_endpoint": "/v1/users/"
    },
    "providers": {
        "list_endpoint": "/v1/providers/"
    }
}

The response has revealed a new API endpoint we now have access to: users.

Exploring Users

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -X GET "https://api.sandbox.yippiemove.com/v1/users/"

Response:

[
    {
        "link": "/v1/users/3/"
    }
]

As expected we receive a list of users back. The list will only contain users the authenticated account is allowed to view. This might be only the authenticated account, but in certain cases you might own a move job which is part of a batch owned by another user. In this case, and similar cases, you'd see the other user too.

The authenticated user is always the first entry in the list.

Examining a User

You can get the current user through the special API endpoint /v1/users/current.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -X GET "https://api.sandbox.yippiemove.com/v1/users/current/"

Response:

{
    "batches": [],
    "created_at": "2012-09-28T07:40:23.858",
    "credits": 0,
    "email": "test@example.com",
    "first_name": "Test",
    "id": 3,
    "last_name": "Testerson",
    "link": "/v1/users/3/",
    "move_jobs": [],
    "orders": []
}

This is our test user. We haven't created any move jobs or orders yet so there isn't much to see. If you check this resource again after a few jobs and orders have been created you'll find them in list format under the appropriate attributes here.

Creating an Order

Time to get down to business. Let's migrate some email. First, let's start a new order. To create something in the API we use the POST method. The API endpoint for orders is /v1/users/{User ID}/orders/.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -X POST "https://api.sandbox.yippiemove.com/v1/users/current/orders/"

Response:

{
    "batches": [],
    "created_at": "2012-10-02T06:11:49.163",
    "credits": 0,
    "move_jobs": [],
    "link": "/v1/users/3/orders/5/",
    "payment": null,
    "owner": {
        "link": "/v1/users/3/"
    },
    "id": 3
}

The new order is empty.

Creating a Move Job

An order can contain one or more "move jobs". Each move job copies email from some email account to another.

The API endpoint for jobs is /v1/users/{User ID}/move_jobs/.

To create a new item we use POST again, but this time we will include some data with our posting. We want to set an attribute of the created job immediately: the order we want the job to belong to. We do this by specifying the resource URL of the order in a JSON POST body.

We have to specify the Content-Type of our posting data using a Content-Type: header.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X POST -d '{"order": "/v1/users/3/orders/5/"}' "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/"

Response:

{
    "last_activity_at": null,
    "created_at": "2012-10-02T06:14:56.097",
    "destination": null,
    "editable": true,
    "updated_at": "2012-10-02T06:14:56.097",
    "contact_part": [],
    "support_id": "A000005",
    "price": 0,
    "source": null,
    "link": "/v1/users/3/move_jobs/5/",
    "batch": null,
    "owner": {
        "link": "/v1/users/3/"
    },
    "id": 5,
    "calendar_part": [],
    "email_part": [],
    "order": {
        "link": "/v1/users/3/orders/5/"
    },
    "stage": "new"
}

Here's our new job. Take a look at the available attributes. Note that the order this move job belongs to is the one we specified in the request.

The Source of the Job

The 'source' account of a move job is where to transfer email from. To specify the source of the new move job, we create a new Account at the source URL.

This time we won't use a POST request. A POST adds a new member to a collection. But in this case there is no collection of Job source Accounts - the Job either has a source Account or it doesn't. So instead we use PUT on the URL for the source:

/v1/users/3/move_jobs/5/accounts/source/

We can use the IMAP settings we found using the provider API, or we can specify a provider by name through the imap_provider attribute. In this case we will specify the settings manually rather than using imap_provider.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X PUT -d '{"ssl": true, "host": "imap.zoho.com", "login": "example@zoho.com", "password": "trustno1", "port": 993}' "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/accounts/source/"

Response:

{
    "xoauth_requestor_id": "",
    "imap_port": 993,
    "xoauth_token_or_consumer_key": "",
    "updated_at": "2012-10-02T13:39:13.693",
    "imap_provider": null,
    "imap_host": "imap.zoho.com",
    "link": "/v1/users/3/move_jobs/5/accounts/source/",
    "move_job": {
        "link": "/v1/users/3/move_jobs/5/"
    },
    "login": "example@zoho.com",
    "id": 6,
    "imap_ssl": true
}

The Destination of the Job

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X PUT -d '{"ssl": true, "host": "imap.gmail.com", "login": "example@mydomain.com", "password": "hax0r", "port": 993}' "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/accounts/destination/"

Response:

{
    "xoauth_requestor_id": "",
    "imap_port": 993,
    "xoauth_token_or_consumer_key": "",
    "updated_at": "2012-10-02T13:49:57.149",
    "imap_provider": null,
    "imap_host": "imap.gmail.com",
    "link": "/v1/users/3/move_jobs/5/accounts/destination/",
    "move_job": {
        "link": "/v1/users/3/move_jobs/5/"
    },
    "login": "example@mydomain.com",
    "id": 7,
    "imap_ssl": true
}

Waiting for Indexing and Checking for Errors

When new Accounts have been added their available email folders will be indexed by YippieMove. Sometimes errors are detected at this stage, such as invalid credentials or a wrong hostname. Let's check if there are any such errors now.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X GET "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/status/"

Response:

{
    "source": {
        "indexed": true,
        "folders": 0,
        "status_message": "Account is indexed",
        "status_code": "account-indexed"
    },
    "destination": {
        "indexed": true,
        "folders": 0,
        "status_message": "Account is indexed",
        "status_code": "account-indexed"
    },
    "overall": {
        "indexed": true,
        "status_code": "missing-email-part",
        "status_message": "An Email Part is required to transfer email."
    }
}

In this case nothing went wrong and both the source and the destination have been fully indexed.

If overall.indexed had been false we would have had to wait for a while and then check again before proceeding. If there had been errors, we would have had to correct them by updating the Job source or destination Account as appropriate, using PUT requests. We will talk more about PUT requests shortly.

Reindexing starts automatically if the Accounts are changed.

Configuring Folders

At this stage we could go ahead and start the job. Before that we will take a look at which folders are available in the source account, in case there are some that we don't want to migrate.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X GET "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/accounts/source/email_folders/"

Response:

[
    {
        "destination_name": "Inbox",
        "selected": true,
        "link": "/v1/users/3/move_jobs/5/accounts/source/email_folders/357/",
        "finished": false,
        "name": "Inbox"
    },
    {
        "destination_name": "Drafts",
        "selected": true,
        "link": "/v1/users/3/move_jobs/5/accounts/source/email_folders/358/",
        "finished": false,
        "name": "Drafts"
    },
    ...
]

This is a sparse representation of each object which only shows a selection of important attributes. As with any sparse object we could get the full representation by issuing a GET for the URL in link.

What if we wanted the full representation of each folder without getting each folder individually?

The Expand Parameter

Some resources accept an optional GET parameter called expand which allows you to pull down more information in a single listing. Let's see if we can get some more information on these accounts.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X GET "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/accounts/source/email_folders/?expand=email_folder"

Response:

[
    {
        "message_select_count": 829,
        "account": {
            "link": "/v1/users/3/move_jobs/5/accounts/source/"
        },
        "messages_unique_count": 0,
        "messages_uploaded_bytes": 0,
        "name": "Inbox",
        "message_list_count": null,
        "attempts_made": 0,
        "messages_downloaded_bytes": 0,
        "messages_uploaded": 0,
        "selected": true,
        "id": 357,
        "note": null,
        "finished": false,
        "link": "/v1/users/3/move_jobs/5/accounts/source/email_folders/357/",
        "message_list_bytes": null,
        "messages_downloaded": 0,
        "separator": "/",
        "destination_name": "Inbox",
        "created_at": "2012-10-02T13:39:16.265"
    },
    {
        "message_select_count": 0,
        "account": {
            "link": "/v1/users/3/move_jobs/5/accounts/source/"
        },
        "messages_unique_count": 0,
        "messages_uploaded_bytes": 0,
        "name": "Drafts",
        "message_list_count": null,
        "attempts_made": 0,
        "messages_downloaded_bytes": 0,
        "messages_uploaded": 0,
        "selected": true,
        "id": 358,
        "note": null,
        "finished": false,
        "link": "/v1/users/3/move_jobs/5/accounts/source/email_folders/358/",
        "message_list_bytes": null,
        "messages_downloaded": 0,
        "separator": "/",
        "destination_name": "Drafts",
        "created_at": "2012-10-02T13:39:16.277"
    },
    ...
]

Deselecting a Folder

Almost all folders are selected for transfer by default (folders like trash and spam are not).

What if we don't want to transfer the Drafts folder? To modify an existing resource we use a PUT request.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X PUT -d '{"selected": false}' "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/accounts/source/email_folders/358/"

Response:

{
    ...
    "name": "Drafts",
    ...
    "selected": false,
    ...
}

If we would check this folder with a GET now we would see that its selected attribute has changed to false.

Using this method we could also have changed the destination name by modifying the destination_name parameter.

Indicate the Type of Job

Before we can start the job we have to specify what we want to transfer. For the sake of future compatibility we have to explicitly select email even though only email can be transferred today.

To do this we add an "email part" to the job.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X POST -d '{}' "https://api.sandbox.yippiemove.com/v1/users/3/move_jobs/5/email_part/"

Response:

{
    "status": "ready",
    "message_select_count": 829,
    "last_activity_at": null,
    "message_list_count": 0,
    "messages_downloaded_bytes": 0,
    "messages_uploaded": 0,
    "messages_unique_count": 0,
    "info_message": null,
    "updated_at": "2012-10-05T13:34:31.861",
    "success_rate": "0",
    "id": 4,
    "link": "/v1/users/3/move_jobs/5/email_part/",
    "message_list_bytes": 0,
    "messages_downloaded": 0,
    "next_run_at": null,
    "messages_uploaded_bytes": 0,
    "move_job": {
        "link": "/v1/users/3/move_jobs/5/"
    },
    "created_at": "2012-10-05T13:34:31.861"
}

Once the job is running, the email part will be updated periodically by YippieMove to indicate information about the transfer.

Starting the Job

We can now start the job by adding a payment for the order the job belongs to. We need to add this to the order we created before, /v1/users/3/orders/5/.

Let's pay for it now. If you haven't already acquired some credits in the sandbox, you should buy some credits now. Credits are free in the sandbox.

Request:

curl -H "Authorization: Bearer FABEFABEFABEFABE" -H "Content-Type: application/json" -X POST -d '{}' "https://api.sandbox.yippiemove.com/v1/users/3/orders/5/payment/"

Response:

{
    "owner": {
        "link": "/v1/users/3/"
    },
    "amount": "15.000",
    "order": {
        "link": "/v1/users/3/orders/5/"
    },
    "created_at": "2012-10-05T13:43:45.354",
    "id": 7
}

If this had been a real job (and not on the sandbox) it would start within a few minutes. The progress could then be monitored by retrieving the email_part.

This concludes the tutorial. Comprehensive information on the available resources and actions is available in the Reference section below.

Reference

API request and response bodies are in the JSON format. Dates are expressed in ISO 8601 format. Integer IDs are 64 bit unsigned longs. String identifiers are unique strings matching [-a-z_].

SSL is required at all times, for all requests.

API Endpoint

https://api.yippiemove.com/v1/

Resource Representation

Resources are represented as JSON dictionaries with named attributes. At a minimum each resource has an attribute named link which is the API URL of the resource itself.

If a resource has many attributes, its minimal representation is one where only the link attribute is presented, and a sparse representation is one where not all attributes are presented (though at least the link attribute).

When a related resource is referred to by an attribute, the value of the attribute is normally the minimal representation of the resource referred to.

Example:

{
    'id': <integer ID of the object>,
    'link': <API URL of the object (a self reference)>,

    'attribute_a': <value of attribute_a>,
    'related_resource_1': {'link': <API URL of related_resource_1>},
}

Lists

Some results from the API contain arrays of resources. These are simply arrays of resource representations. They are normally sparse representations.

Example:

[{'link': <API URL of resource member 1>}, {'link': <API URL of resource member 2>}, ...]

Errors

The API reports errors using standard HTTP status codes.

These are the more common ones:

  • 200 - OK
  • 201 - Created
  • 400 - Bad Request (the request has an error)
  • 401 - Unauthorized
  • 404 - Not Found
  • 500 - Server Error (the server has an error)

If the response code indicates an error, additional error information will be available as JSON in the body of the response.

{
    "code": <the HTTP status code>,
    "description": <a more detailed error description if available>,
    "error": <an error constant, e.g. 'Not Found' for a 404>
}

Sometimes additional information may be available and presented in other attributes.

Verbs

The API presents a basic CRUD mapping to HTTP verbs for most resources.

  • GET - LIST all resources or READ a specific resource.
  • POST - CREATE a new resource.
  • PUT - UPDATE an existing resource, or CREATE a non existing named resource.
  • PATCH - UPDATE an existing resource using a sparse representation.
  • DELETE - REMOVE and existing resource.

YippieMove treats PUT and PATCH the same way. This might change in the future so to change individual attributes, use PATCH.

The purpose of these commands follows standard REST practices. In short: GET of a list endpoint URL lists all resources available, GET of a specific resource URL returns the resource's representation in JSON. POST to a list endpoint URL creates a new resource, PUT changes an existing resource or creates a specific named resource, PATCH to a specific resource URL changes the resource and DELETE of a specific resource URL removes the resource.

On GET, POST, PUT and PATCH Payloads

A GET of a specific URL will return the JSON representation of the resource linked to by the URL. The same representation is used for PUT, PATCH and POST requests.

A resource has a number of attributes, expressed in its JSON representation. For example an Email Part resource has an updated_at attribute and a state attribute among others. When a client is sending data through POST, PUT or PATCH, each attribute is optional in the JSON representation. So for the Email Part case, a PUT could send JSON with only an updated_at field and no state field, or vice versa. In the case of a POST, defaults will be used for attributes not specified. In the case of a PATCH, the existing values remain unchanged after the update. A PUT should transmit all attributes but if not it acts like a PATCH.

When a new resource is created through a successful POST operation the JSON representation of the newly created resources is returned in the response as if the request had been a GET. This allows the client to immediately read back any variable attributes of the new object. For example the client could read back the generated id or created_at attributes of the resource.

Some attributes may generally not be set or modified. For instance the id of a resource is assigned by the server, not the client.

Access Limitations

A regular user can normally only access resources which he or she created. Sometimes a user might have read-only access to related resources, e.g. if a user owns a Batch but not a particular Job in that batch, the user can still view the Job.

If the user has insufficient permissions to perform a particular interaction with a resource, including reading it, the user will receive a 401 error when attempting to do so.

Resources in lists, or related resources in a resource, are by default displayed in a sparse representation form - often the minimal representation.

In select cases the expand query parameter can be used to expand these sparse representations into the full representations. The parameter takes a comma separated list of attribute names to expand.

For example a list of Move Jobs at /v1/users/5/move_jobs/ would look like this normally:

[{'link': '/v1/users/1/move_jobs/1/'}, {'link': '/v1/users/1/move_jobs/2/'}, ...]

Using expand=move_job, forming the new URL /v1/users/5/move_jobs/?expand=move_job, the response would look something like this:

[
    {
        "last_activity_at": null,
        "created_at": "2012-10-02T06:14:56.097",
        "destination": {
            "link": "/v1/users/3/move_jobs/5/accounts/destination/"
        },
        "editable": true,
        "updated_at": "2012-10-02T06:14:56.097",
        "contact_part": [],
        "support_id": "A000005",
        "link": "/v1/users/3/move_jobs/5/",
         ...
    },
    ...
]

/move_jobs/?expand=move_job,move_job__destination would look like this:

[
    {
        "last_activity_at": null,
        "created_at": "2012-10-02T06:14:56.097",
        "destination": {
            "xoauth_requestor_id": "",
            "imap_port": 993,
            "xoauth_token_or_consumer_key": "",
            "updated_at": "2012-10-02T13:50:16.379",
            "imap_provider": null,
            "imap_host": "imap.gmail.com",
            "link": "/v1/users/3/move_jobs/5/accounts/destination/",
            "move_job": {
                "link": "/v1/users/3/move_jobs/5/"
            },
            "login": "lab2@galab.wireload.org",
            "id": 7,
            "imap_ssl": true
        },
        "editable": false,
        "updated_at": "2012-10-05T13:43:45.356",
        "contact_parts": [],
        "support_id": "A000005",
        "price": 15,
        "source": {
            "link": "/v1/users/3/move_jobs/5/accounts/6/"
        },
        ...
    ...
]

The following attributes can be expanded:

  • Move Job List or Resource:
    • move_job
    • move_job__destination
    • move_job__source
    • move_job__email_part
    • move_job__contact_part
    • move_job__calendar_part
  • User List or Resource:
    • user
    • user__move_jobs
    • user__batches
    • user__orders
  • Email Folder List or Resource:
    • email_folder
    • email_folder__account

Resources

YippieMove's API is (fairly) explorable by loading the root URL /v1/ and then following links from there.

This is YippieMove's hierarchy of resources:

  • https://api.yippiemove.com/v1/
    • /
    • users/{User ID}
      • move_jobs/{Move Job ID}
        • email_part/
        • contacts_part/
        • calendars_part/
        • accounts/{Account ID}
          • email_folders/{Email Folder ID}
      • batches/{Batch ID}
      • orders/{Order ID}
        • payment/
    • providers/{Provider ID}

The special user id current can be used to access the currently authenticated user's resource. Example: issuing a GET for https://api.yippiemove.com/v1/users/current/batches/ would return a list of all batches belonging to the current user.

User

Resource URL:

/v1/users/ /v1/users/{User ID}

A registered user of YippieMove. A user can be the owner of various resources, and also has a balance of credits applicable towards starting jobs. Users cannot be created, modified or deleted through the API.

Attributes

  • id: an integer
  • link: the URL of this User resource - a string
  • created_at: the date the User was created - an ISO 8601 date as a string
  • updated_at: the date the User was last changed - an ISO 8601 date as a string

  • first_name: a string

  • last_name: a string
  • email: a string
  • credits: the balance of credits held by the user - an integer
  • move_jobs: the Move Jobs belonging to the User - a list
  • batches: the Batches belonging to the User - a list
  • orders: the Orders belonging to the User - a list

Get a List of Users

  • Method and URL: GET /v1/users/
  • Optional Parameters:
    • created_at__gt: filter by created_at greater than the specified ISO date string.
    • created_at__lt: filter by created_at lesser than the specified ISO date string.
    • offset: an integer count of results to skip.
    • limit: an integer number of maximum results to return. Must be less than 201. Defaults to 200.

The response is a list of User sparse representations.

The first result will always be the currently authenticated user.

View Specific Users

  • Method and URL: GET /v1/users/{User ID}
  • Expand Options:
    • user
    • user__move_jobs
    • user__batches
    • user__orders

Access restriction notes:

If the authenticated user does not have permission to view the credit balance of the requested user, the credits attribute will be null.

Available Methods

  • GET

Move Job

Resource URL:

/v1/users/{User ID}/move_jobs/ /v1/users/{User ID}/move_jobs/{Move Job ID}/

The Move Job represents a transfer of data from a source to a destination. By itself, it does not specify what data will be transferred. One or more associated Email Part, Contacts Part or Calendar Part objects fill this role.

Attributes

  • id: an integer
  • link: the URL of this Move Job resource - a string

  • created_at: the date this Job was created - an ISO 8601 date as a string

  • updated_at: the date this Job was last changed - an ISO 8601 date as a string
  • last_activity_at: the date and time this Job last was processed by YippieMove - an ISO 8601 date as a string

  • batch: the Batch resource this Job belongs to - a resource URL

  • order: the Order resource this Job is a part of - a resource URL
  • owner: the User who owns this Job - a resource URL

  • destination: the Account to transfer data to - a resource URL

  • source: the Account to transfer data from - a resource URL

  • email_part: see Email Part - a resource URL

  • calendar_part: see Calendar Part - a resource URL
  • contact_part: see Contact Part - a resource URL
  • editable: whether this Job can still be changed - a boolean
  • last_activity_at: the date and time this Job last was processed by YippieMove - an ISO 8601 date as a string
  • price: the price of this Job in credits - an integer
  • stage: the stage of this Job - a string from the Stage Constants table
  • support_id: the unique id of this Job seen by the user on yippiemove.com - a string

Transfer Stage Constants

These are the valid values for the Move Job stage attribute.

  • new: this Job is new and unpaid.
  • active: this Job is clear to run and is either running or enqueued to run.
  • done: this Job has been finished.

Get a List of Move Jobs

  • Method and URL: GET /v1/users/{User ID}/move_jobs/
  • Optional Parameters:
    • owner__id filter by owner.
    • created_at__gt filter by created_at greater than the specified ISO date string.
    • created_at__lt filter by created_at lesser than the specified ISO date string.
    • offset an integer count of results to skip.
    • limit an integer number of maximum results to return. Must be less than 201. Defaults to 200.

The response is a list of Move Job sparse representations sorted from oldest to newest.

View Specific Move Jobs

  • Method and URL: GET /v1/users/{User ID}/move_jobs/{Move Job ID}/

Available Methods

  • GET, POST, PUT, PATCH, DELETE

Note that only Move Jobs which still have a stage of new and which are are editable may be deleted.


Email Part

Resource URL:

/v1/users/{User ID}/move_jobs/email_part/

An EmailPart represents the transfer of email for a Move Job.

Attributes

  • id: an integer
  • link: the URL of this Email Part resource - a string

  • created_at: the date this Email Part was created - an ISO 8601 date as a string

  • updated_at: the date this Email Part was last changed - an ISO 8601 date as a string
  • last_activity_at: the date and time this part of the Job was last was processed by YippieMove - an ISO 8601 date as a string
  • next_run_at: the data and time this part of the Job is expected to be evaluated for another potential retry or completion next - an ISO 8601 date as a string

  • move_job: the Job this part is a part of - a resource URL

  • status: a status code for this part of the Job - a string

  • info_message: additional information - a string
  • success_rate: a number from 0.0-1.0 indicating how large a part of the email job YippieMove estimates it has successfully completed - a float

  • message_select_count: the sum of all message_select_counts for each source Email Folder - an integer

  • message_list_count: sum of all message_list_counts for each source Email Folder - an integer
  • message_list_bytes: sum of all message_list_bytes for each source Email Folder - an integer
  • messages_unique_count: sum of all message_unique_counts for each source Email Folder - an integer
  • messages_downloaded: sum of all message_downloaded for each source Email Folder - an integer
  • messages_downloaded_bytes: sum of all message_downloaded_bytes for each source Email Folder - an integer
  • messages_uploaded: sum of all messages_uploaded for each source Email Folder - an integer
  • messages_uploaded_bytes": sum of allmessages_uploaded_bytes` for each source Email Folder - an integer

Status Constants

These are the valid values for the EmailPart status attribute.

  • ready: the part may run whenever the Job runs.
  • run: the part is currently running.
  • pause: the part is waiting to run again.
  • done: the part has been finished.

Get the Email Part of a Job

  • Method and URL: GET /v1/users/{User ID}/move_jobs/email_part/

Available Methods

  • GET, POST, PUT, PATCH, DELETE

A Move Job can have 0 or 1 email parts.


Calendar Part

A Calendar Part represents the transfer of contacts for a Move Job. This functionality is not yet available in YippieMove.


Contacts Part

A Contacts Part represents the transfer of contacts for a Move Job. This functionality is not yet available in YippieMove.


Account

Resource URL:

/v1/users/{User ID}/move_jobs/{Move Job ID}/accounts/source/ /v1/users/{User ID}/move_jobs/{Move Job ID}/accounts/destination/

An account represents a source or a destination account for a Move Job. The same account information is used for the transfer of email, contacts and calendars.

Attributes

  • id: an integer
  • link: the URL of this Account resource - a string

  • created_at: the date this Account was created - an ISO 8601 date as a string

  • updated_at: the date this Account was last changed - an ISO 8601 date as a string

  • move_job: the Job this Account is a part of - a resource URL

  • login: the login or username - a string

  • password: a string
  • xoauth_token_or_consumer_key: used for xoauth authentication - a string
  • xoauth_requestor_id: used for xoauth authentication - a string
  • imap_provider: see Provider - a resource URL
  • imap_host: use this host to connect by IMAP - a string
  • imap_port: use this port to connect by IMAP - a string
  • imap_ssl: whether SSL should be used for IMAP - a string

Specify either an imap_provider, or the imap_host, imap_port, imap_ssl settings.

Available Methods

  • GET, PUT, PATCH, DELETE

To specify a source or destination, PUT the appropriate URL.

Note that only Accounts which belong to Move Jobs which are editable may be deleted.


Email Folder

Resource URL:

/v1/users/{User ID}/move_jobs/{Move Job ID}/accounts/{source|destination}/email_folders/ /v1/users/{User ID}/move_jobs/{Move Job ID}/accounts/{source|destination}/email_folders/{Email Folder ID}/

A folder in an account (or a tag in some systems). The Email Part uses the folder information of the source Account to determine which folders to transfer. Destination Accounts also have folders but these are purely informative.

Attributes

  • id: an integer
  • link: the URL of this Email Folder resource - a string

  • created_at: the date this Folder was created - an ISO 8601 date as a string

  • updated_at: the date this Folder was last changed - an ISO 8601 date as a string

  • account: the Account resource this Job belongs to - a resource URL

  • selected: whether this Folder should be transferred - a boolean

  • name: the name of the Folder - a string

  • destination_name: what the Folder should be called in the destination - a string
  • separator: the Folder separator symbol - a string

  • attempts_made: how many attempts were made to transfer this Folder - an integer

  • finished: whether this Folder is considered finished - a boolean
  • note: any status message associated with this Folder - a string

  • message_select_count: a high estimate of the number of emails in this Folder seen when it was indexed - an integer

  • message_list_count: a high estimate of the number of emails in this Folder from when it was last scanned - an integer
  • message_list_bytes: the size of all emails seen when this Folder was last scanned - an integer
  • messages_unique_count: the number of unique emails seen when this Folder was last scanned - an integer
  • messages_downloaded: the number of emails downloaded from this Folder
  • messages_downloaded_bytes: the number of bytes downloaded from this Folder
  • messages_uploaded: the number of emails uploaded to the destination for this Folder
  • messages_uploaded_bytes: the number of bytes uploaded to the destination for this Folder

Get a List of Email Folders for a particular Account

  • Method and URL: GET /v1/users/{User ID}/move_jobs/{Move Job ID}/accounts/{source|destination}/email_folders/
  • Optional Parameters:
    • owner__id filter by owner.
    • created_at__gt filter by created_at greater than the specified ISO date string.
    • created_at__lt filter by created_at lesser than the specified ISO date string.
    • offset an integer count of results to skip.
    • limit an integer number of maximum results to return. Must be less than 201. Defaults to 200.

The response is a list of Email Folders belonging to the Account.

Available Methods

  • GET, PUT, PATCH

YippieMove automatically creates and removes folders as it indexes Accounts.

Batches

Resource URL:

/v1/users/{User ID}/batches/ /v1/users/{User ID}/batches/{Batch ID}

A Batch is a group of Move Jobs. Grouping Move Jobs together into a Batch can be useful to organise jobs. It is also possible to have a different owner for a Batch than for the individual jobs under some circumstances.

The Batch will be visible in the web interface on yippiemove.com under the specified name. All Jobs in a Batch which is added to an Order will become part of that Order just like if they had been added separately.

Attributes

  • id: an integer
  • link: the URL of this Batch resource - a string

  • created_at: the date this Batch was created - an ISO 8601 date as a string

  • updated_at: the date this Batch was last changed - an ISO 8601 date as a string

  • order: the Order resource this Batch is a part of - a resource URL

  • owner: the User who owns this Batch - a resource URL

  • move_jobs: list of Jobs belonging to this Batch - a list

  • name: a 'nickname' for this Batch - a string
  • price: the price of this Batch in Credits - an integer

The price is equal to the sum of the price of the Move Jobs in the Batch.

Available Methods

  • GET, POST, PUT, PATCH, DELETE

Orders

Resource URL:

/v1/users/{User ID}/orders/ /v1/users/{User ID}/orders/{Order ID}/

Orders are used to pay for Jobs and Batches. To purchase a service through YippieMove, create an Order with the desired Jobs and Batches and then POST a Payment to it.

The use of a Batch is optional. A group of Move Jobs can be put into an Order by themselves, or they can be grouped into a Batch which is then added to the Order.

Attributes

  • id: an integer
  • link: the URL of this Order resource - a string

  • created_at: the date this Order was created - an ISO 8601 date as a string

  • updated_at: the date this Order was last changed - an ISO 8601 date as a string

  • owner: the User who owns this Order - a resource URL

  • batches: list of Batches belonging to this Order

  • move_jobs: list of Jobs belonging to this Order
  • price: the price of this Order in Credits - an integer
  • payment: see Payment - a resource URL

The price is equal to the sum of the price of the Batches and Jobs in the Order.

Available Methods

  • GET, POST, PUT, PATCH

Payments

Resource URL:

/v1/users/{User ID}/orders/{Order ID}/payment/

A Payment represents a payment for an Order. When an Order is fully paid, the Jobs and Batches which belong to it can start.

To pay for an Order, POST a Payment for it. The necessary amount of credits will be withdrawn from the account of the authenticated user. The cost of an Order can be read from its read-only price attribute. It will always be equal to the sum of the price attributes of its Batches and Jobs.

Attributes

  • id: an integer
  • link: the URL of this Payment resource - a string

  • created_at: the date this Payment was created - an ISO 8601 date as a string

  • owner: the User who owns this Payment - a resource URL

  • order: the Order which this Payment was made for - a resource URL

  • amount: the number of Credits that was paid - an integer

Available Methods

  • GET, POST

Creating a new payment costs credits. The credits are deducted from the user's account.

Payments cannot be changed once made. Only one Payment can be made for every Order. Once an Order has been paid for it can no longer be edited.

An Order can only be paid for if:

  • It has at least one Move Job.
  • Each Job in the Order has an Email Part.
  • Each Job in the Order has a source and a destination Account, both of which have been successfully indexed.
  • The Job has no errors.
  • There are enough Credits in the current user's account.

Provider

Resource URL:

/v1/providers/ /v1/providers/{Provider ID}/

A Provider represents one of the service providers known to YippieMove. The Providers may be used in Accounts to describe where the account belongs - e.g. a Provider could be Gmail and an Account could be with Gmail by settings its imap_provider to the URL of the Gmail Provider.

Some providers are 'hidden' - they might be referenced by jobs but are still not readable by the user. These providers are used internally within YippieMove.

Attributes

  • identifier: a string
  • link: the URL of this Provider resource - a string

  • name: the name of this Provider - a string

  • category: a category such as "Business" or "University" - a string
  • imap_host: IMAP host to use with this Provider - a string
  • imap_port: IMAP port to user with this Provider - an integer
  • imap_ssl: whether SSL should be used with this Provider - a boolean

Get a List of Providers

  • Method and URL: GET /v1/providers/
  • Optional Parameters:
    • offset - An integer count of results to skip.
    • limit - An integer number of maximum results to return. Must be less than 201. Defaults to 200.

The response is a list of Providers.

Available Methods

  • GET