Quick Start Guide

Get up and running with Mailhooks in just a few minutes. This guide will walk you through setting up your first domain and receiving emails.

Step 1

Create Your Account

If you haven't already, sign up for a Mailhooks account. You'll get a free tier that includes:

1 domain

Custom email domain

100 emails/month

Receive up to 100 emails

100 API req/min

Generous rate limits

Step 2

Add Your Domain

After logging in, navigate to the Domains section in your dashboard:

1Click "Add Domain"
2Enter your domain name (e.g., mail.yourdomain.com)
3Copy the DNS records provided
4Add these records to your domain's DNS settings
5Wait for verification (usually takes 5-30 minutes)

💡 Tip: Use a subdomain like mail.yourdomain.com instead of your root domain to avoid conflicts with existing email services.

Step 3

Create an API Key

1Go to API Keys in your dashboard
2Click "Create API Key"
3Give it a descriptive name like "Production App"
4Copy and securely store the generated key

💡 Pro Tip: Use our TypeScript SDK for type-safe API access. Install with: npm install @mailhooks/sdk

Step 4

Set Up a Webhook (Recommended)

Webhooks allow you to receive real-time notifications when emails arrive:

1Go to Webhooks in your dashboard
2Click "Create Webhook"
3Enter your endpoint URL (e.g., https://your-app.com/api/webhooks/mailhooks)
4Select the "email.received" event
5Save your webhook

Example Webhook Handler (Node.js/Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/api/webhooks/mailhooks', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'email.received') {
    console.log('New email received!');
    console.log('From:', data.from);
    console.log('Subject:', data.subject);

    // Process the email
    await processEmail(data);
  }

  res.status(200).send('OK');
});

async function processEmail(email) {
  // Your email processing logic here
  // e.g., save to database, trigger notifications, etc.
}

Step 5

Send a Test Email

Once your domain is verified, send a test email to any address at your domain:

Example addresses:

[email protected]
[email protected]
Any address will work!

If you set up a webhook, you'll see the request hit your endpoint immediately. You can also retrieve the email via the API:

Using cURL

curl -H "x-api-key: mh_your_api_key_here" \
     https://mailhooks.dev/api/v1/emails

Using TypeScript SDK

import { Mailhooks } from '@mailhooks/sdk';

const mailhooks = new Mailhooks({
  apiKey: 'mh_your_api_key_here'
});

// Get all emails
const emails = await mailhooks.emails.list();

// Get the latest email
const latestEmail = emails.data[0];
console.log('Latest email:', latestEmail.subject);

Next Steps

📧 Explore the Emails API

Learn how to retrieve, filter, and manage emails programmatically.

🔔 Configure Webhooks

Set up real-time notifications for incoming emails.

⚡ TypeScript SDK

Use our type-safe SDK for easier integration and better DX.

✨ Best Practices

Learn how to handle emails efficiently and securely.

import { Mailhooks } from '@mailhooks/sdk'; const mailhooks = new Mailhooks({ apiKey: 'mh_your_api_key_here' }); // Get all emails const emails = await mailhooks.emails.list(); // Get the latest email const latestEmail = emails.data[0]; console.log('Latest email:', latestEmail.subject);