Mailisk

Appearance

Email ​

/api

The Email API lets you search namespace inboxes, fetch email attachments, list namespaces, and retrieve SMTP settings for sending test email.

Endpoints ​

MethodEndpointDescription
GET/api/emails/{namespace}/inboxSearch emails in a namespace inbox
GET/api/attachments/{id}Get an email attachment download URL
GET/api/namespacesList namespaces available to the API key
GET/api/smtp/{namespace}Get SMTP settings for a namespace

Search Inbox ​

GET /api/emails/{namespace}/inbox

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

sh
curl --request GET \
     --url https://api.mailisk.com/api/emails/{namespace}/inbox \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}' \
     --get \
     --data-urlencode 'to_addr_prefix=something@'
js
const { data: emails } = await mailisk.searchInbox(namespace, {
  to_addr_prefix: "something@",
});

WARNING

The mailisk and cypress-mailisk libraries default to using the wait flag. This means the request will keep waiting until at least one matching email is returned. Direct API requests do not use this flag by default, but it can be added manually.

Waiting for email ​

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

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

WARNING

Since this request will never timeout on its own, set a timeout in your integration tests.

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

Response ​

json
{
  "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,
      "headers": {
        "from": "test@test.com",
        "to": "something@test.mailisk.net",
        "subject": "This is a test",
        "content-type": "text/html; charset=UTF-8"
      },
      "attachments": [
        {
          "id": "123",
          "filename": "attachment.txt",
          "content_type": "text/plain",
          "size": 100
        }
      ]
    }
  ]
}

Get Attachment ​

GET /api/attachments/{id}

This endpoint returns the attachment for a specific ID.

Attachment IDs are stored in the id field of the attachments array in the Search Inbox response.

sh
curl --request GET \
     --url https://api.mailisk.com/api/attachments/{id} \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'
js
const attachment = await mailisk.getAttachment(attachmentId);

Path Params ​

NameDescription
idThe UUID of the attachment to get.

Response ​

json
{
  "data": {
    "id": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019",
    "filename": "lorem-ipsum.txt",
    "content_type": "text/plain",
    "size": 446,
    "expires_at": "2026-04-28T08:24:58.000Z",
    "download_url": "https://example.com/attachments/1777112698913_5e0c23bc-dc1c-49f3-8d92-9a0d85527019.txt"
  }
}

List Namespaces ​

GET /api/namespaces

This endpoint returns all owned namespaces.

sh
curl --request GET \
     --url https://api.mailisk.com/api/namespaces \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'
js
const { data: namespaces } = await mailisk.listNamespaces();

Response ​

json
{
  "total_count": 1,
  "data": [
    {
      "id": "67f3dcb7-a707-422b-a907-5da53f026fe3",
      "namespace": "test",
      "shared": false,
      "settings": {
        "retention_time": 86400,
        "quota_limit": 19000
      }
    }
  ]
}

Get SMTP Settings ​

GET /api/smtp/{namespace}

This endpoint returns the SMTP settings for a specific namespace.

sh
curl --request GET \
     --url https://api.mailisk.com/api/smtp/{namespace} \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'
js
const smtpSettings = await mailisk.getSmtpSettings(namespace);

Path Params ​

NameDescription
namespaceThe namespace to get SMTP settings for.

Response ​

json
{
  "data": {
    "host": "smtp.mailisk.net",
    "port": 587,
    "username": "mynamespace@mailisk.net",
    "password": "password"
  }
}

Typescript types ​

typescript
interface NamespaceListResponse {
  total_count: number;
  data: Namespace[];
}

interface Namespace {
  /** Unique UUID for namespace */
  id: string;
  /** Namespace */
  namespace: string;
  /** Shared namespace */
  shared?: boolean;
  settings: {
    retention_time: number;
    quota_limit?: number | null;
  };
}

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

interface EmailAttachmentSummary {
  /** Unique identifier for the attachment */
  id: string;
  /** Filename of the attachment */
  filename: string;
  /** Content type of the attachment */
  content_type: string;
  /** Size in bytes of the attachment */
  size: number;
}

interface EmailSearchResponse {
  total_count: number;
  options: {
    limit: number;
    offset: number;
    from_timestamp?: number;
    to_timestamp?: number;
    to_addr_prefix?: string;
    from_addr_includes?: string;
    subject_includes?: string;
    wait?: boolean;
  };
  data: Email[];
}

interface Email {
  /** Namespace scoped ID */
  id: string;
  /** Sender of email */
  from: EmailAddress;
  /** Recipients 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 in seconds that this email was received */
  received_timestamp: number;
  /** The Unix timestamp in seconds when this email will be deleted */
  expires_timestamp: number;
  /** The raw email headers */
  headers?: Record<string, string>;
  /** Attachments of the email */
  attachments?: EmailAttachmentSummary[];
}

interface Attachment {
  data: {
    /** Unique identifier for the attachment */
    id: string;
    /** Filename of the attachment */
    filename: string;
    /** Content type of the attachment */
    content_type: string;
    /** Size in bytes of the attachment */
    size: number;
    /** The datetime when this attachment will be deleted */
    expires_at: string | null;
    /** The URL to the attachment */
    download_url: string;
  };
}

interface SmtpSettings {
  data: {
    host: string;
    port: number;
    username: string;
    password: string;
  };
}