Getting Started with MERU

MERU is the fastest way to add inbound email processing to your application. In this guide, you’ll create your first inbound email address and receive your first webhook in under 5 minutes.

What You’ll Build

By the end of this guide, you’ll have:

• A working inbound email address
• A webhook endpoint receiving structured JSON
• Your first inbound email processed

Step 1: Get Your API Token

1. Sign up at app.meruhook.com
2. Navigate to Settings > API Tokens
3. Click Create Token and give it a name
4. Copy your token - you’ll need it for API calls

Keep your token secure! Never commit it to version control or share it publicly.

Step 2: Create Your First Inbound Address

Use the API to create an email address that forwards to your webhook:

curl -X POST https://api.meruhook.com/v1/addresses \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.com/webhook",
    "is_permanent": true
  }'

Response:

{
  "id": "addr_abc123",
  "address": "user123@inbound.meruhook.com",
  "webhook_url": "https://your-app.com/webhook",
  "is_enabled": true,
  "is_permanent": true,
  "expires_at": null,
  "email_count": 0,
  "created_at": "2025-09-05T10:00:00Z"
}

🎉 You now have a working inbound email address!

Step 3: Set Up Your Webhook Endpoint

Create an endpoint in your application to receive inbound emails:

app.post('/webhook', express.json(), (req, res) => {
  const email = req.body;
  
  console.log('Subject:', email.headers.subject);
  console.log('From:', email.envelope.mail_from);
  console.log('Text:', email.text);
  console.log('Attachments:', email.attachments.length);
  
  // Process the email data
  // Your business logic here
  
  res.status(200).send('OK');
});

from flask import Flask, request, jsonify

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    email = request.json
    
    print(f"Subject: {email['headers']['subject']}")
    print(f"From: {email['envelope']['mail_from']}")
    print(f"Text: {email['text']}")
    print(f"Attachments: {len(email['attachments'])}")
    
    # Process the email data
    # Your business logic here
    
    return 'OK', 200

Route::post('/webhook', function (Request $request) {
    $email = $request->json()->all();
    
    Log::info('Inbound Email', [
        'subject' => $email['headers']['subject'],
        'from' => $email['envelope']['mail_from'],
        'text' => $email['text'],
        'attachments' => count($email['attachments'])
    ]);
    
    // Process the email data
    // Your business logic here
    
    return response('OK');
});

Step 4: Send Your First Test Email

1. Send an email to the address you created: user123@inbound.meruhook.com
2. Check your webhook endpoint logs
3. You should see the structured JSON data!

Understanding the Webhook Payload

Every inbound email is delivered as structured JSON:

{
  "event_id": "evt_abc123",
  "address_id": "addr_abc123",
  "envelope": {
    "mail_from": "sender@example.com",
    "rcpt_to": ["user123@inbound.meruhook.com"]
  },
  "headers": {
    "from": "Sender Name <sender@example.com>",
    "to": "user123@inbound.meruhook.com",
    "subject": "Test Email",
    "date": "2025-09-05T10:30:00Z",
    "message_id": "<abc123@example.com>"
  },
  "text": "Plain text email content",
  "html": "<p>HTML email content</p>",
  "attachments": [
    {
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "content": "base64-encoded-content...",
      "size": 12345
    }
  ],
  "spam": {
    "score": 0.1,
    "verdict": "not_spam"
  },
  "timestamp": "2025-09-05T10:30:00Z"
}

Next Steps

Now that you have basic inbound email working, explore these advanced features:

🔐 Secure Your Webhooks

• Verify webhook signatures for security
• Implement proper authentication in your webhook handler

📊 Monitor Usage

• Check your usage statistics via API
• Set up billing alerts and limits

🛠️ Advanced Features

• Create temporary addresses with expiration
• Enable spam filtering for better email quality
• Use data enrichment for enhanced email data

📚 Integration Guides

• Laravel SDK - Complete Laravel package
• Node.js Examples - Express, Fastify, Next.js
• Python Examples - Django, FastAPI, Flask

Common Issues

Webhook Not Receiving Data

1. Check your URL - Make sure it’s publicly accessible
2. Verify HTTPS - Webhooks require SSL/TLS
3. Check response codes - Return 200 OK status
4. Review logs - Check your application logs for errors

Email Not Arriving

1. Verify address - Double-check the email address spelling
2. Check spam folder - Some providers filter inbound emails
3. Test with different sender - Try from Gmail, Outlook, etc.

Need Help?

• 📧 Email us: support@meruhook.com
• 💬 Chat: Available in your dashboard
• 📖 Documentation: You’re reading it!

Ready for production? Learn about authentication, error handling, and scaling your inbound email processing.