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

{
  "total_count": 1,
  "options": {
    "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
    }
  ]
}

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 and subject_includes 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@", subject_includes: "password reset", 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 and subject *password reset* (case insensitive) arrives.

Warning

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

Request

Path Params

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

Query

Name	Required	Type	Description
limit	Optional	Number	The maximum number of emails that can be returned in this request. Must be between 1 and 20
offset	Optional	Number	The number of emails to skip/ignore, useful for pagination.
from_timestamp	Optional	Number	Filter emails by starting unix timestamp in seconds.
to_timestamp	Optional	Number	Filter emails by ending unix timestamp in seconds.
to_addr_prefix	Optional	String	Filter emails by 'to' address. Address must start with this. Example: 'foo' would return for 'foobar@...' but not 'barfoo@...'
from_addr_includes	Optional	String	Filter emails by 'from' address. Address must include this. Example: '@foo' would return for 'a@foo.com', 'b@foo.net'
subject_includes	Optional	String	Filter emails by subject. This is case insensitive. Subject must include this. Example: 'password' would return for 'Password reset', 'Reset password notification' but not 'Reset'
wait	Optional	Boolean	If 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;
}