cypress-mailisk 3.2.1 → 3.3.0

package/README.md

@@ -5,7 +5,7 @@ Mailisk is an end-to-end email and SMS testing platform. It allows you to receiv
 - Get a unique subdomain and unlimited email addresses for free.
 - Easily automate E2E password reset and account verification by catching emails.
 - Receive SMS messages and automate SMS tests.
-- Virtual SMTP and SMS support to test without 3rd party clients.
+- Outbound email and virtual SMS support to test without 3rd party clients.
 
 ## Get started
 
@@ -148,6 +148,71 @@ cy.mailiskDownloadAttachment('attachment-id').then((buffer) => {
 });
 ```
 
+### Outbound email
+
+These commands create, queue, and inspect outbound email delivery through the Mailisk API.
+
+```js
+cy.mailiskSendEmail('mynamespace', {
+  from: {
+    email: 'support@mynamespace.mailisk.net',
+    name: 'Support',
+  },
+  to: ['verified@example.com'],
+  subject: 'Hello from Mailisk',
+  text: 'This is the plain text body.',
+  html: '<p>This is the HTML body.</p>',
+}).then((outboundEmail) => {
+  expect(outboundEmail.status).to.equal('queued');
+
+  cy.mailiskGetOutboundEmail(outboundEmail.id).then((detail) => {
+    expect(detail.recipients).to.not.be.empty;
+  });
+});
+```
+
+Messages sent only to the same namespace do not consume outbound usage because they are counted as inbound email when delivered.
+
+Send an outbound email with an attachment:
+
+```js
+cy.fixture('report.txt', 'base64').then((contentBase64) => {
+  cy.mailiskSendEmail('mynamespace', {
+    to: ['verified@example.com'],
+    subject: 'Report',
+    text: 'Attached.',
+    attachments: [
+      {
+        filename: 'report.txt',
+        content_type: 'application/octet-stream',
+        content_base64: contentBase64,
+      },
+    ],
+  });
+});
+```
+
+Reply to an inbound email returned by `cy.mailiskSearchInbox()`:
+
+```js
+cy.mailiskSearchInbox('mynamespace', {
+  to_addr_prefix: 'support@mynamespace.mailisk.net',
+}).then((response) => {
+  cy.mailiskReplyToEmail(response.data[0].id, {
+    text: 'Thanks, we received your message.',
+  });
+});
+```
+
+Forward an inbound email:
+
+```js
+cy.mailiskForwardEmail('inbound-email-id', {
+  to: ['verified@example.com'],
+  text: 'Forwarding this along.',
+});
+```
+
 ### cy.mailiskSearchSms
 
 This is the main command to interact with Mailisk SMS, it wraps the [Search SMS](/api-reference/search-sms) endpoint. Use a phone number that is registered to your account.
@@ -214,7 +279,7 @@ cy.mailiskListSmsNumbers().then((response) => {
 
 ### TOTP authenticator devices
 
-These commands manage saved Mailisk Authenticator devices and generate OTP codes through the Mailisk API. Use an organisation API key for these endpoints.
+These commands manage saved Mailisk Authenticator devices and generate OTP codes through the Mailisk API.
 
 ```js
 cy.mailiskDeviceList({ issuer: 'GitHub', username: 'qa@example.com' }).then((response) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress-mailisk",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Mailisk library for Cypress",
   "keywords": [
     "mailisk",

package/src/mailiskCommands.d.ts

@@ -219,6 +219,227 @@ export interface SendVirtualSmsParams {
   body: string;
 }
 
+export type OutboundEmailType = 'new' | 'reply' | 'forward';
+
+export type OutboundEmailStatus = 'queued' | 'sending' | 'sent' | 'failed';
+
+export type OutboundEmailRecipientType = 'to' | 'cc' | 'bcc';
+
+export type OutboundEmailRecipientDeliveryStatus =
+  | 'pending'
+  | 'accepted'
+  | 'queued'
+  | 'sent'
+  | 'delayed'
+  | 'deferred'
+  | 'delivered'
+  | 'bounced'
+  | 'expired'
+  | 'complained'
+  | 'unsubscribed'
+  | 'suppressed'
+  | 'rejected'
+  | 'failed'
+  | 'cancelled';
+
+export type OutboundEmailEventType =
+  | 'accepted'
+  | 'queued'
+  | 'sent'
+  | 'failed'
+  | 'rejected'
+  | 'delayed'
+  | 'deferred'
+  | 'delivered'
+  | 'bounced'
+  | 'expired'
+  | 'complained'
+  | 'unsubscribed'
+  | 'suppressed'
+  | 'cancelled'
+  | 'opened'
+  | 'clicked';
+
+export type OutboundEmailAttachmentDisposition = 'attachment' | 'inline';
+
+export interface OutboundEmailAddress {
+  /** Email address */
+  email: string;
+  /** Display name, if one is specified */
+  name?: string;
+}
+
+export interface OutboundEmailAttachment {
+  /** Filename of the attachment */
+  filename: string;
+  /** MIME content type */
+  content_type: string;
+  /** Base64 encoded attachment content */
+  content_base64: string;
+  /** Content-ID for inline attachments */
+  content_id?: string;
+  /** Attachment disposition */
+  disposition?: OutboundEmailAttachmentDisposition;
+}
+
+export interface SendEmailParams {
+  /** Optional sender override. Must belong to the requested namespace. */
+  from?: OutboundEmailAddress;
+  /** Optional Reply-To address */
+  reply_to?: OutboundEmailAddress;
+  /** Primary recipients */
+  to?: string[];
+  /** Carbon-copied recipients */
+  cc?: string[];
+  /** Blind carbon-copied recipients */
+  bcc?: string[];
+  /** Email subject */
+  subject: string;
+  /** HTML message body */
+  html?: string;
+  /** Plain text message body */
+  text?: string;
+  /** Attachments to include */
+  attachments?: OutboundEmailAttachment[];
+}
+
+export interface ReplyToEmailParams {
+  /** Optional sender override. Must belong to the source email namespace. */
+  from?: OutboundEmailAddress;
+  /** Carbon-copied recipients */
+  cc?: string[];
+  /** Blind carbon-copied recipients */
+  bcc?: string[];
+  /** Optional subject. Defaults to Re: original subject. */
+  subject?: string;
+  /** HTML reply body */
+  html?: string;
+  /** Plain text reply body */
+  text?: string;
+  /** Attachments to include */
+  attachments?: OutboundEmailAttachment[];
+}
+
+export interface ForwardEmailParams {
+  /** Optional sender override. Must belong to the source email namespace. */
+  from?: OutboundEmailAddress;
+  /** Primary recipients */
+  to: string[];
+  /** Carbon-copied recipients */
+  cc?: string[];
+  /** Blind carbon-copied recipients */
+  bcc?: string[];
+  /** Optional subject. Defaults to Fwd: original subject. */
+  subject?: string;
+  /** Optional HTML body to prepend before the forwarded message */
+  html?: string;
+  /** Optional plain text body to prepend before the forwarded message */
+  text?: string;
+}
+
+export interface OutboundEmailResponse {
+  id: string;
+  organisation_id: string;
+  type: OutboundEmailType;
+  status: OutboundEmailStatus;
+  from: OutboundEmailAddress;
+  reply_to?: OutboundEmailAddress;
+  subject: string;
+  recipient_count: number;
+  attachment_count: number;
+  message_id: string;
+  provider?: string;
+  provider_message_id?: string;
+  failure_reason?: string;
+  queued_at: string;
+  sending_at?: string;
+  sent_at?: string;
+  failed_at?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface OutboundEmailDeliverySummary {
+  pending: number;
+  accepted: number;
+  queued: number;
+  sent: number;
+  delayed: number;
+  deferred: number;
+  delivered: number;
+  bounced: number;
+  expired: number;
+  complained: number;
+  unsubscribed: number;
+  suppressed: number;
+  rejected: number;
+  failed: number;
+  cancelled: number;
+}
+
+export interface OutboundEmailRecipient {
+  id: string;
+  type: OutboundEmailRecipientType;
+  email: string;
+  name?: string;
+  delivery_status: OutboundEmailRecipientDeliveryStatus;
+  last_event_type?: string;
+  last_event_at?: string;
+  accepted_at?: string;
+  queued_at?: string;
+  sent_at?: string;
+  delayed_at?: string;
+  deferred_at?: string;
+  delivered_at?: string;
+  bounced_at?: string;
+  expired_at?: string;
+  complained_at?: string;
+  unsubscribed_at?: string;
+  suppressed_at?: string;
+  rejected_at?: string;
+  failed_at?: string;
+  cancelled_at?: string;
+  last_smtp_code?: string;
+  last_enhanced_status_code?: string;
+  last_smtp_response?: string;
+  attempt_count: number;
+  bounce_type?: string;
+  bounce_subtype?: string;
+  bounce_classification?: string;
+  complaint_feedback_type?: string;
+}
+
+export interface OutboundEmailEventRecipient {
+  id: string;
+  outbound_email_recipient_id?: string;
+  email: string;
+  smtp_code?: string;
+  enhanced_status_code?: string;
+  smtp_response?: string;
+  diagnostic_code?: string;
+  action?: string;
+  attempt_count?: number;
+  bounce_classification?: string;
+}
+
+export interface OutboundEmailEvent {
+  id: string;
+  provider: string;
+  provider_message_id?: string;
+  provider_event_id?: string;
+  event_type: OutboundEmailEventType;
+  event_subtype?: string;
+  occurred_at: string;
+  recipients: OutboundEmailEventRecipient[];
+  created_at: string;
+}
+
+export interface OutboundEmailDetailResponse extends OutboundEmailResponse {
+  delivery_summary: OutboundEmailDeliverySummary;
+  recipients: OutboundEmailRecipient[];
+  events: OutboundEmailEvent[];
+}
+
 export type TotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512';
 
 export type KnownTotpDeviceSource = 'shared_secret' | 'custom' | 'base32_secret_key' | 'otpauth_url';
@@ -400,6 +621,70 @@ declare global {
         options?: Partial<Cypress.RequestOptions>,
       ): Cypress.Chainable<Buffer>;
 
+      mailiskSendEmail(
+        /**
+         * Namespace to send from.
+         */
+        namespace: string,
+        /**
+         * Outbound email input.
+         */
+        input: SendEmailParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<OutboundEmailResponse>;
+
+      mailiskGetOutboundEmail(
+        /**
+         * Outbound email ID returned by mailiskSendEmail, mailiskReplyToEmail, or mailiskForwardEmail.
+         */
+        outboundEmailId: string,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<OutboundEmailDetailResponse>;
+
+      mailiskReplyToEmail(
+        /**
+         * Inbound email ID returned by mailiskSearchInbox.
+         */
+        emailId: string,
+        /**
+         * Reply input.
+         */
+        input: ReplyToEmailParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<OutboundEmailResponse>;
+
+      mailiskForwardEmail(
+        /**
+         * Inbound email ID returned by mailiskSearchInbox.
+         */
+        emailId: string,
+        /**
+         * Forward input.
+         */
+        input: ForwardEmailParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<OutboundEmailResponse>;
+
       mailiskSearchSms(
         /**
          * The phone number to search.

package/src/mailiskCommands.js

@@ -8,6 +8,10 @@ class MailiskCommands {
       'mailiskSearchInbox',
       'mailiskGetAttachment',
       'mailiskDownloadAttachment',
+      'mailiskSendEmail',
+      'mailiskGetOutboundEmail',
+      'mailiskReplyToEmail',
+      'mailiskForwardEmail',
       'mailiskSearchSms',
       'mailiskListSmsNumbers',
       'mailiskDeviceList',
@@ -134,6 +138,28 @@ class MailiskCommands {
     );
   }
 
+  mailiskSendEmail(namespace, input, options = {}) {
+    const urlParams = this._buildUrlParams({ namespace: this._requireNonEmptyString(namespace, 'namespace') });
+    return this._withRequest((request) => request.post(`api/emails/send?${urlParams.toString()}`, input, options));
+  }
+
+  mailiskGetOutboundEmail(outboundEmailId, options = {}) {
+    const encodedOutboundEmailId = encodeURIComponent(
+      this._requireNonEmptyString(outboundEmailId, 'outboundEmailId'),
+    );
+    return this._withRequest((request) => request.get(`api/emails/outbound/${encodedOutboundEmailId}`, options));
+  }
+
+  mailiskReplyToEmail(emailId, input, options = {}) {
+    const encodedEmailId = encodeURIComponent(this._requireNonEmptyString(emailId, 'emailId'));
+    return this._withRequest((request) => request.post(`api/emails/${encodedEmailId}/reply`, input, options));
+  }
+
+  mailiskForwardEmail(emailId, input, options = {}) {
+    const encodedEmailId = encodeURIComponent(this._requireNonEmptyString(emailId, 'emailId'));
+    return this._withRequest((request) => request.post(`api/emails/${encodedEmailId}/forward`, input, options));
+  }
+
   _mailiskSearchSmsAction(request, phoneNumber, _options, urlParams, startTime, nextTimeout) {
     return request
       .get(`api/sms/${phoneNumber}/messages?${urlParams.toString()}`, { ..._options, timeout: nextTimeout })