Skip to content

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



curl --request GET \
     --url{namespace}/inbox \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'


  "total_count": 1,
  "options": {
    "limit": 10,
    "offset": 0
  "data": [
      "id": "1656255823893-tk8rrslxv",
      "from": {
        "address": "",
        "name": ""
      "to": {
        "address": "",
        "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";

  .get(`${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",

This request will never timeout and will only return when an email matching special-tag@{namespace} and subject *password reset* (case insensitive) arrives.


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


Path Params

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


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 for 'foobar@...' but not 'barfoo@...'
from_addr_includesOptionalStringFilter emails by 'from' address. Address must include this. Example: '@foo' would return for '', ''
subject_includesOptionalStringFilter emails by subject. This is case insensitive. Subject must include this. Example: 'password' would return for 'Password reset', 'Reset password notification' but not 'Reset'
waitOptionalBooleanIf this flag is true then the request will keep waiting till at least one response is returned. See Waiting for email.


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;