Cypress email testing
No Cypress plugin is required: use cy.request against a real InboxRhino inbox to test signup verification, OTP codes, magic links and password resets. Wait up to 180 seconds for mail, handle HTTP 200 matches and HTTP 204 timeouts separately, then delete the inbox to release its active-inbox quota.
Signup / OTP example
Create an inbox, run your signup flow, wait for matching mail, inspect its content and clean up in afterEach, which Cypress runs after a failing test too. A 204 response has no JSON body.
const API = 'https://api.inboxrhino.in';
let inboxId: string | undefined;
describe('signup email verification', () => {
beforeEach(function () {
if (!Cypress.env('INBOXRHINO_API_KEY')) this.skip();
});
afterEach(() => {
if (inboxId) {
const id = inboxId;
inboxId = undefined;
cy.request({
method: 'DELETE',
url: `${API}/v1/inboxes/${id}`,
headers: { Authorization: `Bearer ${Cypress.env('INBOXRHINO_API_KEY')}` },
failOnStatusCode: false,
}).its('status').should('eq', 204);
}
});
it('completes signup through the verification email', () => {
const key = Cypress.env('INBOXRHINO_API_KEY') as string;
const startedAt = new Date().toISOString();
const prefix = `signup-${Date.now().toString(36)}`;
cy.request({
method: 'POST',
url: `${API}/v1/inboxes`,
headers: { Authorization: `Bearer ${key}` },
body: { prefix },
}).then((created) => {
expect(created.status).to.eq(201);
inboxId = created.body.data.id as string;
const address = created.body.data.address as string;
cy.visit(Cypress.env('SIGNUP_URL') || 'http://localhost:3000/signup');
cy.get('[data-cy=email]').type(address);
cy.get('[data-cy=signup-submit]').click();
return cy.request({
method: 'GET',
url: `${API}/v1/inboxes/${inboxId}/messages`,
qs: {
wait_seconds: 180,
limit: 1,
include: 'content',
subject: 'Verify',
sender: 'noreply@example.com',
received_after: startedAt,
},
headers: { Authorization: `Bearer ${key}` },
timeout: 190_000,
failOnStatusCode: false,
});
}).then((mail) => {
if (mail.status === 204) throw new Error('No matching email arrived within 180 seconds');
expect(mail.status).to.eq(200);
expect(mail.body.data).to.have.length(1);
const message = mail.body.data[0];
const content = `${message.text ?? ''}\n${message.html ?? ''}`;
const verificationUrl = content.match(/https?:\/\/[^\s"'<>]+/i)?.[0];
expect(verificationUrl, 'Verification link missing from email').to.exist;
cy.visit(verificationUrl!);
cy.contains(/verified|account is ready/i).should('be.visible');
});
});
});Adapt the application-specific lines
Replace the signup URL, form selectors, sender or subject filter and success assertion. Keep the InboxRhino lifecycle, received_after boundary and cleanup unchanged. If the email has several links, parse the link owned by your application rather than assuming the first href is correct.
Extracting an OTP vs a magic link
InboxRhino returns parsed message content; your test must parse the OTP from text or HTML. OTP extraction is not built into v1. For a magic link, select the application-owned URL from the message.
CI notes
- Store
INBOXRHINO_API_KEYas a CI secret or Cypress environment variable. Never commit it. - Use
received_afterif an earlier matching message could still be in the inbox. - Delete the inbox in cleanup so failed assertions do not use an active-inbox slot. Deleting a message does not restore monthly email quota.
GitHub Actions
Use a staging URL whose application can send real email. Keep the API key in repository or environment secrets.
name: Cypress email test
on: [push]
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22, cache: npm }
- run: npm ci
- run: npx cypress run
env:
INBOXRHINO_API_KEY: ${{ secrets.INBOXRHINO_API_KEY }}
SIGNUP_URL: https://staging.example.com/signupLimits that affect Cypress suites
InboxRhino is receive-only, and messages are retained for 30 days. The live free plan allows 11 active inboxes and 33 inbound emails per UTC month. Paid checkout is not open; see pricing and quotas for current status.
FAQ
Do I need a Cypress plugin to test email with InboxRhino?
No. cy.request against the InboxRhino REST API is enough.
How long will InboxRhino wait for the email?
Up to 180 seconds in one request. A match returns HTTP 200; a timeout returns HTTP 204 with an empty body. Do not parse JSON on 204.
How do I stop Cypress from timing out before the wait ends?
Set the cy.request timeout higher than 180 seconds.
What happens if I forget to delete the inbox?
It counts toward the active-inbox cap until you delete it.
Can I use this in GitHub Actions?
Yes, with a real mail-sending staging environment and the API key stored as a secret.
Where is the Playwright version of this guide?
See the Playwright email testing guide at /docs/playwright.
Start with the API quickstart and API reference. Also see Playwright email testing or the longer news article, Testing email OTP flows in Cypress using temporary API inboxes by Dennis Farren (12 September 2026).