{"_id":"56b8d3a55d75fe0d00fbcca5","user":"5582e90181672a3900bb4fc7","version":{"_id":"569f9cf6650e1d1900f96b5e","project":"569f9cf6650e1d1900f96b5b","__v":12,"createdAt":"2016-01-20T14:43:02.785Z","releaseDate":"2016-01-20T14:43:02.785Z","categories":["569f9cf7650e1d1900f96b5f","56abdd81d4432d1900eed235","56abe0558beeff0d003b8118","56ad2f8b1c09150d00a183a8","56ad4e1cd21f1b0d00fd2f97","56b00ad88f7a4f0d0029dc92","56b2432e9621f20d00efb2bd","56b25826147e900d00d6497a","56b7af2a4b372d2100722c48","56b8c4d938b1070d0028920f","56b8cdab14feef0d0082415d","58599813cf9e112d0032cdab"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"56b8cdab14feef0d0082415d","__v":5,"pages":["56b8cdd914feef0d0082415e","56b8cebd38b1070d00289220","56b8d26f38b1070d00289226","56b8d3a55d75fe0d00fbcca5","56b8d74d86d2b0190070bd7a"],"project":"569f9cf6650e1d1900f96b5b","version":"569f9cf6650e1d1900f96b5e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-08T17:17:31.562Z","from_sync":false,"order":9999,"slug":"migration-methods","title":"Migration methods"},"project":"569f9cf6650e1d1900f96b5b","__v":18,"githubsync":"","parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-08T17:43:01.125Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"## Syntax \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    <credentials object> \\n    \\\"job\\\": <job id>\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request fields for migration_status\"\n}\n[/block]\nThe following fields can be used in the **migration_status** method:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"job\",\n    \"0-1\": \"Required\",\n    \"0-2\": \"The ID of the job you are querying.\\n\\nThe ID is returned in the [migration_add](https://api-opensrs-email.readme.io/v1.0/docs/migration_add?bypass=8272e34bb5) response.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response fields for migration_status\"\n}\n[/block]\nThe following fields may be returned when the **migration_status** method is submitted:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Description/Value\",\n    \"0-0\": \"error\",\n    \"0-1\": \"Returned if **success = false**\",\n    \"0-2\": \"A text string that explains the error.\",\n    \"1-0\": \"error_number\",\n    \"1-1\": \"Returned if **success = false**\",\n    \"1-2\": \"A number that represents the error.\",\n    \"2-0\": \"rate\",\n    \"2-1\": \"Returned if **success = true**\",\n    \"2-2\": \"The aggregate throughput rate for the entire migration job (for all users).\",\n    \"3-0\": \"success\",\n    \"3-1\": \"Always returned\",\n    \"3-2\": \"Indicates whether the requested change was successful or not. Allowed values are **true** and **false**.\",\n    \"4-0\": \"users\",\n    \"4-1\": \"Returned if **success = true**\",\n    \"4-2\": \"Information about the migration job. \\n\\nAllowed values are:\\n\\n  * **data** — Information about the migration, including the following: \\n\\n   * **config** — Details about the user's migration. Includes the following information:\\n    \\n    * **method** — The method used (imap4, imap4s, pop3, or pop3s) \\n    \\n    * **server** — The server from which the job is pulling data.\\n    \\n    * **username** — The remote username used to log in.\\n\\n  * **folders** — Details about each of the folders that are being migrated. Includes the following information: \\n\\n    * **bytes** — Number of bytes migrated.\\n    \\n    * **delim** — The hierarchy delimiter that the remote imap server uses to separate nested folder names. Our imap server uses \\\".\\\", the\\nexample uses \\\"/\\\" - so a folder named \\\"INBOX/Sent\\\" on the remote end would end up as \\\"INBOX.Sent\\\" on our end after migration.\\n\\n    * **fail_count** — Number of messages that failed to migrate and will not be retried.\\n    \\n    * **migrate_count** —   Number of messages migrated.\\n    \\n    * **next_uid** — Response from the remote imap server as to what the next unique identifier (uid) will be.\\n    \\n    * **remote_count** —   Number of messages on the remote imap/pop server.\\n    \\n    * **retry1count** — Number of messages that will have their first retry attempt (after failing on the first attempt).\\n    \\n    * **retry2count** — Number of messages that will have their second retry attempt (after failing on the first and second attempts). If they fail again, they go into **fail_count.**\\n    \\n    * **skip_count** — Number of messages that will not be migrated either because they were migrated in a previous migration or because the request said to skip the folder.\\n    \\n  * **status** — Current status of all folders in aggregate. Includes the following information:\\n   \\n    * **bytes** — Total number of bytes migrated.\\n    \\n    * **critical_errors** — Total number of critical errors encountered. If there are too many critical errors, the migration is aborted for the user.\\n    \\n    * **fail_count** — Number of messages that failed to migrate.\\n    \\n    * **foldercount** — Number of folders present on the remote server.\\n    \\n    * **migrate_count** — Total number of messages migrated.\\n    \\n    * **remote_count** —  Number of messages present on the remote server.\\n    \\n    * **skip_count** — Total number of messages skipped.\\n\\n  * **local** — The user to whom mail is being migrated.\\n  * **state**—The progress of the migration. Allowed values are:\\n  \\n   * **active**—Phase 2 in process, mailbox being actively migrated.\\n   \\n   * **complete** — Phase 2 complete, mailbox migrated.\\n   \\n   * **error** — Errors in phase1 or phase2, migration aborted.\\n   \\n   * **pending** — Migration accepted and enqueued;; hasn't started processing yet.\\n   \\n   * **validated** — Phase 1 complete, waiting for phase 2 (full migration).\\n   \\n   * **validating** — Phase 1 in progress - login credentials being tested, remote message counts being gathered.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples for migration_status\"\n}\n[/block]\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin:::at:::example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n \\\"job\\\":\\\"1326229437638\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"rate\\\": \\\"613.499 KiB/s\\\",\\n  \\\"success\\\": true,\\n  \\\"users\\\": [\\n     {\\n      \\\"data\\\": {\\n        \\\"folders\\\": {\\n          \\\"INBOX\\\": {\\n            \\\"next_uid\\\": \\\"5\\\",\\n            \\\"bytes\\\": 123133,\\n            \\\"migrate_count\\\": 5,\\n            \\\"fail_count\\\": 0,\\n            \\\"retry1count\\\": 0,\\n            \\\"skip_count\\\": 0,\\n            \\\"remote_count\\\": \\\"5\\\",\\n            \\\"retry2count\\\": 0,\\n            \\\"delim\\\": \\\".\\\"\\n          }, \\n          \\\"Trash\\\": {\\n            \\\"next_uid\\\": \\\"1\\\",\\n            \\\"skip_count\\\": \\\"1\\\",\\n            \\\"delim\\\": \\\".\\\",\\n            \\\"remote_count\\\": \\\"1\\\"\\n         },\\n         \\\"Drafts\\\": {\\n           \\\"next_uid\\\": \\\"0\\\",\\n           \\\"delim\\\": \\\".\\\",\\n           \\\"remote_count\\\": \\\"0\\\"\\n         }, \\n         \\\"Spam\\\": {\\n           \\\"next_uid\\\": \\\"1\\\",\\n           \\\"skip_count\\\": \\\"1\\\",\\n           \\\"delim\\\": \\\".\\\",\\n           \\\"remote_count\\\": \\\"1\\\"\\n         },\\n         \\\"Sent Items\\\": {\\n           \\\"next_uid\\\": \\\"0\\\",\\n           \\\"delim\\\": \\\".\\\",\\n           \\\"remote_count\\\": \\\"0\\\"\\n         } \\n      },\\n       \\\"status\\\": {\\n         \\\"bytes\\\": 123133,\\n         \\\"fail_count\\\": 0,\\n         \\\"migrate_count\\\": 5,\\n         \\\"skip_count\\\": 2,\\n         \\\"critical_errors\\\": \\\"0\\\",\\n         \\\"foldercount\\\": 5,\\n         \\\"remote_count\\\": \\\"7\\\"\\n       },\\n       \\\"config\\\": {\\n         \\\"server\\\": \\\"mail.bigmail.com:993\\\", \\n         \\\"method\\\": \\\"imap4s\\\",\\n         \\\"remote\\\": \\\"joseph.user@bigmail.com\\\"\\n       } \\n     },\\n     \\\"local\\\": \\\"joe_user@example.com\\\",\\n     \\\"state\\\": \\\"complete\\\"\\n    }\\n  ] \\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]","excerpt":"The **migration_status** method provides detailed information about the\nprogress and results of a migration job.","slug":"migration_status","type":"basic","title":"migration_status"}

migration_status

The **migration_status** method provides detailed information about the progress and results of a migration job.

## Syntax [block:code] { "codes": [ { "code": "{\n <credentials object> \n \"job\": <job id>\n}", "language": "perl", "name": " " } ] } [/block] [block:api-header] { "type": "basic", "title": "Request fields for migration_status" } [/block] The following fields can be used in the **migration_status** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "job", "0-1": "Required", "0-2": "The ID of the job you are querying.\n\nThe ID is returned in the [migration_add](https://api-opensrs-email.readme.io/v1.0/docs/migration_add?bypass=8272e34bb5) response." }, "cols": 3, "rows": 1 } [/block] [block:api-header] { "type": "basic", "title": "Response fields for migration_status" } [/block] The following fields may be returned when the **migration_status** method is submitted: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Description/Value", "0-0": "error", "0-1": "Returned if **success = false**", "0-2": "A text string that explains the error.", "1-0": "error_number", "1-1": "Returned if **success = false**", "1-2": "A number that represents the error.", "2-0": "rate", "2-1": "Returned if **success = true**", "2-2": "The aggregate throughput rate for the entire migration job (for all users).", "3-0": "success", "3-1": "Always returned", "3-2": "Indicates whether the requested change was successful or not. Allowed values are **true** and **false**.", "4-0": "users", "4-1": "Returned if **success = true**", "4-2": "Information about the migration job. \n\nAllowed values are:\n\n * **data** — Information about the migration, including the following: \n\n * **config** — Details about the user's migration. Includes the following information:\n \n * **method** — The method used (imap4, imap4s, pop3, or pop3s) \n \n * **server** — The server from which the job is pulling data.\n \n * **username** — The remote username used to log in.\n\n * **folders** — Details about each of the folders that are being migrated. Includes the following information: \n\n * **bytes** — Number of bytes migrated.\n \n * **delim** — The hierarchy delimiter that the remote imap server uses to separate nested folder names. Our imap server uses \".\", the\nexample uses \"/\" - so a folder named \"INBOX/Sent\" on the remote end would end up as \"INBOX.Sent\" on our end after migration.\n\n * **fail_count** — Number of messages that failed to migrate and will not be retried.\n \n * **migrate_count** — Number of messages migrated.\n \n * **next_uid** — Response from the remote imap server as to what the next unique identifier (uid) will be.\n \n * **remote_count** — Number of messages on the remote imap/pop server.\n \n * **retry1count** — Number of messages that will have their first retry attempt (after failing on the first attempt).\n \n * **retry2count** — Number of messages that will have their second retry attempt (after failing on the first and second attempts). If they fail again, they go into **fail_count.**\n \n * **skip_count** — Number of messages that will not be migrated either because they were migrated in a previous migration or because the request said to skip the folder.\n \n * **status** — Current status of all folders in aggregate. Includes the following information:\n \n * **bytes** — Total number of bytes migrated.\n \n * **critical_errors** — Total number of critical errors encountered. If there are too many critical errors, the migration is aborted for the user.\n \n * **fail_count** — Number of messages that failed to migrate.\n \n * **foldercount** — Number of folders present on the remote server.\n \n * **migrate_count** — Total number of messages migrated.\n \n * **remote_count** — Number of messages present on the remote server.\n \n * **skip_count** — Total number of messages skipped.\n\n * **local** — The user to whom mail is being migrated.\n * **state**—The progress of the migration. Allowed values are:\n \n * **active**—Phase 2 in process, mailbox being actively migrated.\n \n * **complete** — Phase 2 complete, mailbox migrated.\n \n * **error** — Errors in phase1 or phase2, migration aborted.\n \n * **pending** — Migration accepted and enqueued;; hasn't started processing yet.\n \n * **validated** — Phase 1 complete, waiting for phase 2 (full migration).\n \n * **validating** — Phase 1 in progress - login credentials being tested, remote message counts being gathered." }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "Examples for migration_status" } [/block] **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"job\":\"1326229437638\"\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"rate\": \"613.499 KiB/s\",\n \"success\": true,\n \"users\": [\n {\n \"data\": {\n \"folders\": {\n \"INBOX\": {\n \"next_uid\": \"5\",\n \"bytes\": 123133,\n \"migrate_count\": 5,\n \"fail_count\": 0,\n \"retry1count\": 0,\n \"skip_count\": 0,\n \"remote_count\": \"5\",\n \"retry2count\": 0,\n \"delim\": \".\"\n }, \n \"Trash\": {\n \"next_uid\": \"1\",\n \"skip_count\": \"1\",\n \"delim\": \".\",\n \"remote_count\": \"1\"\n },\n \"Drafts\": {\n \"next_uid\": \"0\",\n \"delim\": \".\",\n \"remote_count\": \"0\"\n }, \n \"Spam\": {\n \"next_uid\": \"1\",\n \"skip_count\": \"1\",\n \"delim\": \".\",\n \"remote_count\": \"1\"\n },\n \"Sent Items\": {\n \"next_uid\": \"0\",\n \"delim\": \".\",\n \"remote_count\": \"0\"\n } \n },\n \"status\": {\n \"bytes\": 123133,\n \"fail_count\": 0,\n \"migrate_count\": 5,\n \"skip_count\": 2,\n \"critical_errors\": \"0\",\n \"foldercount\": 5,\n \"remote_count\": \"7\"\n },\n \"config\": {\n \"server\": \"mail.bigmail.com:993\", \n \"method\": \"imap4s\",\n \"remote\": \"joseph.user@bigmail.com\"\n } \n },\n \"local\": \"joe_user@example.com\",\n \"state\": \"complete\"\n }\n ] \n}", "language": "perl", "name": " " } ] } [/block]