Email

/api/emails

The Email API lets you search namespace inboxes, fetch individual inbound emails, and fetch email attachments.

Endpoints

Method	Endpoint	Description
`GET`	`/api/emails/{namespace}/inbox`	Search emails in a namespace inbox
`GET`	`/api/emails/{emailId}`	Get a single inbound email
`POST`	`/api/emails/{emailId}/deliverability-report`	Generate a deliverability report
`GET`	`/api/emails/{emailId}/deliverability-report`	Get a deliverability report
`GET`	`/api/emails/{emailId}/attachments`	Get email attachment download URLs
`GET`	`/api/attachments/{id}`	Get an attachment download URL by ID

Search Inbox

GET /api/emails/{namespace}/inbox

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

cURLNode

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@'

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

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 or 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` returns `foobar@...` but not `barfoo@...`.
`from_addr_includes`	Optional	String	Filter emails by `from` address. Address must include this. Example: `@foo` returns `a@foo.com` and `b@foo.net`.
`subject_includes`	Optional	String	Filter emails by subject. This is case insensitive. Subject must include this. Example: `password` returns `Password reset`, but not `Reset`.
`wait`	Optional	Boolean	If 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": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019",
          "filename": "attachment.txt",
          "content_type": "text/plain",
          "size": 100
        }
      ]
    }
  ]
}

Get Inbound Email

GET /api/emails/{emailId}

This endpoint returns a single inbound email by ID.

cURLNode

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

const response = await fetch(`https://api.mailisk.com/api/emails/${emailId}`, {
  headers: {
    Accept: 'application/json',
    'X-Api-Key': apiKey,
  },
});
const { data: email } = await response.json();

Path Params

Name	Description
`emailId`	The ID of the inbound email to get.

Response

json

{
  "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": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019",
        "filename": "attachment.txt",
        "content_type": "text/plain",
        "size": 100
      }
    ]
  }
}

Generate Deliverability Report

POST /api/emails/{emailId}/deliverability-report

This endpoint generates or refreshes a deliverability report for an inbound email.

cURLNode

curl --request POST \
     --url https://api.mailisk.com/api/emails/{emailId}/deliverability-report \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'

const response = await fetch(`https://api.mailisk.com/api/emails/${emailId}/deliverability-report`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'X-Api-Key': apiKey,
  },
});
const report = await response.json();

Path Params

Name	Description
`emailId`	The ID of the inbound email to generate the report for.

Response

json

{
  "status": "pending",
  "analysis_version": "v1",
  "expires_at": "2026-04-28T08:24:58.000Z"
}

Get Deliverability Report

GET /api/emails/{emailId}/deliverability-report

This endpoint returns a deliverability report for an inbound email.

cURLNode

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

const response = await fetch(`https://api.mailisk.com/api/emails/${emailId}/deliverability-report`, {
  headers: {
    Accept: 'application/json',
    'X-Api-Key': apiKey,
  },
});
const report = await response.json();

Path Params

Name	Description
`emailId`	The ID of the inbound email to get the report for.

Response

json

{
  "status": "completed",
  "analysis_version": "v1",
  "expires_at": "2026-04-28T08:24:58.000Z",
  "report": {
    "overall_status": "no_issues",
    "source": {
      "namespace": "test",
      "email_id": "1656255823893-tk8rrslxv",
      "received_timestamp": 1656255823
    },
    "spf": { "status": "pass", "issues": [] },
    "dkim": { "status": "pass", "issues": [] },
    "dmarc": { "status": "pass", "issues": [] },
    "blocklists": { "status": "pass", "issues": [] },
    "spamassassin": { "status": "pass", "issues": [] },
    "content": { "status": "pass", "issues": [] },
    "dns": { "status": "pass", "issues": [] }
  }
}

Get Email Attachments

GET /api/emails/{emailId}/attachments

This endpoint returns download metadata for every attachment on an inbound email.

cURLNode

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

const response = await fetch(`https://api.mailisk.com/api/emails/${emailId}/attachments`, {
  headers: {
    Accept: 'application/json',
    'X-Api-Key': apiKey,
  },
});
const { data: attachments } = await response.json();

Path Params

Name	Description
`emailId`	The ID of the inbound email to get attachments for.

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"
    }
  ]
}

Get Attachment by ID

GET /api/attachments/{id}

This endpoint returns download metadata for a specific attachment ID.

Attachment IDs are stored in the id field of the attachments array in email responses.

cURLNode

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

const attachment = await mailisk.getAttachment(attachmentId);

Path Params

Name	Description
`id`	The 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"
  }
}

Typescript types

typescript

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 InboundEmailResponse {
  data: Email;
}

type DeliverabilityReportStatus = 'pending' | 'running' | 'completed' | 'failed';
type DeliverabilitySectionStatus = 'pass' | 'warning' | 'fail';

interface DeliverabilityReportResponse {
  status: DeliverabilityReportStatus;
  analysis_version: string;
  expires_at: string | null;
  report?: {
    overall_status: 'no_issues' | 'warning' | 'issue_detected';
    source: {
      namespace: string;
      email_id: string;
      received_timestamp: number;
    };
    spf: DeliverabilitySection;
    dkim: DeliverabilitySection;
    dmarc: DeliverabilitySection;
    blocklists: DeliverabilitySection;
    spamassassin: DeliverabilitySection;
    content: DeliverabilitySection;
    dns: DeliverabilitySection;
  };
  errors?: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  }[];
}

interface DeliverabilitySection {
  status: DeliverabilitySectionStatus;
  issues: {
    code: string;
    message: string;
    severity?: DeliverabilitySectionStatus;
    details?: Record<string, unknown>;
  }[];
  [key: string]: unknown;
}

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 AttachmentResponse {
  data: Attachment;
}

interface Attachment {
  /** 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 EmailAttachmentsResponse {
  data: Attachment[];
}

Email ​

Endpoints ​

Search Inbox ​

Waiting for email ​

Path Params ​

Query ​

Response ​

Get Inbound Email ​

Path Params ​

Response ​

Generate Deliverability Report ​

Path Params ​

Response ​

Get Deliverability Report ​

Path Params ​

Response ​

Get Email Attachments ​

Path Params ​

Response ​

Get Attachment by ID ​

Path Params ​

Response ​

Typescript types ​

Email

Endpoints

Search Inbox

Waiting for email

Path Params

Query

Response

Get Inbound Email

Path Params

Response

Generate Deliverability Report

Path Params

Response

Get Deliverability Report

Path Params

Response

Get Email Attachments

Path Params

Response

Get Attachment by ID

Path Params

Response

Typescript types