Skip to content
On this page

Search Inbox

GET /api/emails/{namespace}/inbox

This endpoint returns the latest emails from a specific namespace's inbox.

Full example can be found at Reading Emails via API

Example

Request

curl --request GET \
     --url https://api.mailisk.com/api/emails/{namespace}/inbox \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'

Response

{
  "options": {
    "total_count": 1,
    "limit": 10,
    "offset": 0
  },
  "data": [
    {
      "id": "1656255823893-tk8rrslxv",
      "from": {
        "address": "test@test.com",
        "name": ""
      },
      "to": {
        "address": "something@test.mailisk.net",
        "name": ""
      },
      "subject": "This is a test",
      "html": "Hello world",
      "text": "Hello world",
      "received_date": "2022-06-26T15:03:43.000Z",
      "received_timestamp": 1656255823,
      "expires_timestamp": 1656259423,
      "spam_score": -1
    }
  ]
}

Waiting for email

When waiting to receive email you can use the wait parameter instead of querying multiple times. This will keep redirecting to the same request until the result would return at least one matching email (total_count >= 1).

This can be combined with the other parameters like to_addr_prefix to listen for specific emails.

Here's an example:

import axios from "axios";

const namespace = "mynamespace";

axios
  .get(`https://api.mailisk.com/api/emails/${namespace}/inbox`, {
    params: { limit: 10, to_addr_prefix: "sepcial-tag@", wait: true },
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "API_KEY",
    },
  })
  .then(console.log);

This request will never timeout and will only return when an email matching special-tag@{namespace}.mailisk.net arrives.

Warning

Since this request will never timeout you should set a timeout in your integration tests.

Request

Path Params

NameDescription
namespaceThe namespace to get emails from. The namespace is the same as when sending emails to something@{namespace}.mailisk.net

Query

NameRequiredTypeDescription
limitOptionalNumberThe maximum number of emails that can be returned in this request. Must be between 1 and 20
offsetOptionalNumberThe number of emails to skip/ignore, useful for pagination.
from_timestampOptionalNumberFilter emails by starting unix timestamp in seconds.
to_timestampOptionalNumberFilter emails by ending unix timestamp in seconds.
to_addr_prefixOptionalStringFilter emails by 'to' address. Address must start with this. Example: 'foo' would return 'foobar@...' but not 'barfoo@...'
waitOptionalBooleanIf this flag is true then the request will keep waiting till at least one response is returned. See Waiting for email.

Response

Typescript type

interface EmailAddress {
  /** Email address */
  address: string;
  /** Display name, if one is specified */
  name?: string;
}

interface Email {
  /** Namespace scoped ID */
  id: string;
  /** Sender of email */
  from: EmailAddress;
  /** Recepients of email */
  to: EmailAddress[];
  /** Carbon-copied recipients for email message */
  cc?: EmailAddress[];
  /** Blind carbon-copied recipients for email message */
  bcc?: EmailAddress[];
  /** Subject of email */
  subject?: string;
  /** Email content that was sent in HTML format */
  html?: string;
  /** Email content that was sent in plain text format */
  text?: string;
  /** The datetime that this email was received */
  received_date: Date;
  /** The unix timestamp (s) that this email was received */
  received_timestamp: number;
  /** The unix timestamp (s) when this email will be deleted */
  expires_timestamp: number;
  /** The spam score as reported by SpamAssassin */
  spam_score?: number;
}