Pagination

Search…
Pagination
Provides the ability to separate and traverse through pages of data
Various APIs provide the ability to query results in a paginated form. These APIs will typically have an optional nextToken input property to facilitate pagination. By default, if a limit is not provided, or set as undefined/nil/null, the default limit will be 10.
When specifying a large number of records in a query, an upper limit of 1MB is enforced on the data retrieved. This limit is applied before any filter is applied to the data. If the 1MB limit is hit, the data will be returned as a page and require using the next token of the result to query the next page of results.
The following types support pagination:
Email Addresses
Email Messages
Email Folders
If intending to use pagination, the first call to an API should not include a nextToken, otherwise the result will return an error. When a paginated API call is successful, the output response will contain a nextToken property.
When using a query that supports pagination, it is important to always check the nextToken. Due to the nature of the data access from the service, it is possible to retrieve a result with no data but potentially have another page of information to retrieve which may contain results.
To access the next page of a query API, use the previously returned nextToken in the subsequent API call. If a successful response does not return a nextToken, or it is set to undefined/nil/null, the pagination results have been exhausted and there are no more pages to retrieve.
When using subsequent calls for pagination, ensure that the input information (e.g. limit, filter) is the same for each call, otherwise unexpected behavior will occur. For example, if the first call uses an input property of limit = 8, then each subsequent call must use a limit of 8.
Pagination Example
TypeScript
iOS
Below is an example usage of getEmailAddresses for a user with four email addresses and paginating through the results:
1
const output: EmailAddress[] = []
2
let nextToken: string | undefined = undefined
3
try {
4
  do {
5
    const listOutput = await emailClient.listEmailAddresses({
6
      cachePolicy: CachePolicy.RemoteOnly,
7
      limit = 2,
8
      nextToken, // `undefined` on first invocation
9
    })
10
    output.push(...listOutput.items)
11
    nextToken = listOutput.nextToken
12
  } while (nextToken)
13
} catch {
14
  // Handle/notify user of errors
15
}
Copied!
The first iteration of the do...while loop will have the listOutput return an array of items containing two EmailAddress objects, as well as a populated nextToken which is used in the subsequent call in the next iteration. The second iteration will have the listOutput return an array of items containing two EmailAddress objects, however the nextToken will be undefined as there are no more objects for the query to fetch.
Below is an example usage of getEmailAddressesWithFilter for a user with 4 email addresses:
1
let semaphore = DispatchSemaphore(value: 0)
2
​
3
var output: ListOutput<EmailAddress>?
4
client.getEmailAddressesWithFilter(nil, limit: 2, nextToken: nil, cachePolicy: .remoteOnly) { result in
5
  switch result {
6
  case let .success(resultOutput):
7
    /*
8
     * This result will contain an `items` array of 2 Email Address objects, as
9
     * well as a non-`nil` `nextToken` which is used in the subsequent call.
10
     */
11
    output = resultOutput
12
    semaphore.signal()
13
  case let .failure(error):
14
    // Handle and cleanup after error.
15
  }
16
}
17
​
18
semaphore.wait()
19
​
20
client.getEmailAddressesWithFilter(nil, limit: 2, nextToken: output?.nextToken, cachePolicy: .remoteOnly) { result in
21
  switch result {
22
  case let .success(resultOutput):
23
    /*
24
     * This result will also contain 2 objects in the `items` array, however the
25
     * `nextToken` will be `nil`, as there are no more objects for the user to
26
     * fetch.
27
     */
28
  case let .failure(error):
29
    // Handle and cleanup after error.
30
  }
31
}
Copied!
​DispatchSemaphore was used for simplifying the demonstration, we strongly recommend using GCD's Operation for handling asynchronous code.
Manage Email Folders & Draft Email
Caching
Last modified 21d ago
Copy link
Contents
Pagination Example