Mailboxes

List mailbox inbox messages

List JMAP messages for a mailbox with opaque cursor, date, folder, keyword, and search filters. The first page fixes the before cutoff. The cursor is bound to the mailbox and filters; send it unchanged and never parse or fabricate it.

get/mailboxes/{id}/inbox/messages

Request

  • Base URL: https://shipmail.to/api/v1
  • URL: https://shipmail.to/api/v1/mailboxes/{id}/inbox/messages
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://shipmail.to/api/auth/oauth2/authorize, token URL https://shipmail.to/api/auth/oauth2/token)

Query parameters

folder_idstring

Filter messages to a specific mailbox folder ID.

folder_role'inbox' | 'starred' | 'sent' | 'drafts' | 'archive' | 'junk' | 'trash'

Filter messages by a system folder role. Use either folder_id or folder_role, not both.

search_textstring

Full-text search query. Max 500 characters.

fromstring

Return messages whose From name or address matches this text. Max 500 characters.

tostring

Return messages whose To recipients match this text by name or address. Cc and Bcc are not searched. Max 500 characters.

subjectstring

Return messages whose subject matches this text. Max 500 characters.

has_attachment'true' | 'false'

true returns messages with an attachment, false returns messages without one. Any other value is rejected.

cursorstring

Opaque pagination cursor returned by the same list operation. Send it unchanged; do not parse, modify, or fabricate it.

afterstring date-time

Only messages received at or after this instant.

beforestring date-time

Only messages received before this instant. Defaults to the first-page snapshot time.

limitinteger

Number of messages to return (1-100, default 50).

has_keyword'$flagged' | '$seen' | '$draft' | '$answered' | '$forwarded'

Return messages that have this JMAP keyword.

not_keyword'$flagged' | '$seen' | '$draft' | '$answered' | '$forwarded'

Return messages that do not have this JMAP keyword.

Headers

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Response

Mailbox inbox messages.

object'inbox_messages' required
mailbox_idstring required
addressstring email required
junk_totalinteger nullable required

Messages in Junk that match the other filters. Counted on the first page when a folder filter leaves Junk out, so an empty Inbox can be told apart from mail held as spam. Null otherwise.

Changes

No recorded changes to this operation across all 1 revision of this API.