MyWarranties API

Appearance

Email Integration ​

MyWarranties features comprehensive email integration via Resend for both sending and receiving emails.

Overview ​

The email system enables:

  • Outbound emails - Notifications sent to users
  • Inbound emails - Users can reply via email
  • Bidirectional communication - Complete email conversations

Outbound Email ​

When Emails Are Sent ​

Emails are automatically sent when:

  1. New claim message - Notify the other party
  2. Warranty expiration - Alert before warranty expires
  3. Claim status change - Notify about status updates

Email Content ​

Each email includes:

  • Subject with product name
  • Message content (HTML + plain text)
  • Link to view claim in app
  • Reply-to address with embedded claim ID
  • Attachments (if any)

Example Email ​

From: MyWarranties <noreply@my-warranties.nl>
Reply-To: claim+123@my-warranties.nl
Subject: New message about iPhone 15 Pro

New Message - iPhone 15 Pro

From: John Supplier
Claim: iPhone 15 Pro

Message:
We received your claim and will investigate the issue.
We'll need some additional photos of the defect.

To reply: Simply reply to this email, and your message
will be added to the claim chat.

[View in App]

Inbound Email (Webhooks) ​

How It Works ​

  1. User replies to notification email
  2. Email sent to claim+123@my-warranties.nl
  3. Resend receives email at your domain
  4. Webhook triggered - POST to /api/inbound/email
  5. Message created in the claim
  6. Real-time update via Mercure
  7. Push notification sent to other party

Webhook Endpoint ​

POST /api/inbound/email

Security ​

Webhooks are secured with:

  • HMAC-SHA256 signature - Verifies request is from Resend
  • Timestamp validation - Prevents replay attacks (5 min window)
  • Authorization check - Sender must be part of claim

Webhook Headers ​

http
svix-id: msg_abc123xyz
svix-timestamp: 1234567890
svix-signature: v1,base64encodedhmacsha256signature

Setup ​

1. Configure Resend ​

In your .env:

env
MAILER_DSN=smtp://resend:re_your_api_key@smtp.resend.com:587
MAILER_FROM_EMAIL=noreply@my-warranties.nl
MAILER_FROM_NAME=MyWarranties
APP_URL=https://my-warranties.nl
RESEND_WEBHOOK_SECRET=whsec_your_webhook_secret

2. Add Domain ​

  1. Go to Resend Dashboard
  2. Add your domain
  3. Configure DNS records (MX, TXT, SPF, DKIM)
  4. Verify domain

3. Set Up Inbound Email ​

  1. Go to Inbound in Resend dashboard
  2. Create inbound rule:
    • Match: claim+*@my-warranties.nl
    • Forward to: https://api.my-warranties.nl/api/inbound/email
  3. Copy webhook signing secret
  4. Add to .env as RESEND_WEBHOOK_SECRET

4. Test Configuration ​

bash
php bin/test-resend.php check-config

Supported Email Formats ​

The webhook endpoint supports multiple providers:

Resend Format ​

json
{
  "type": "email.received",
  "data": {
    "from": "user@example.com",
    "to": ["claim+123@my-warranties.nl"],
    "subject": "Re: Warranty Claim",
    "text": "Reply text",
    "html": "<p>Reply text</p>",
    "attachments": []
  }
}

Postmark Format ​

json
{
  "FromFull": {
    "Email": "user@example.com"
  },
  "ToFull": [{
    "Email": "claim+123@my-warranties.nl"
  }],
  "TextBody": "Reply text",
  "HtmlBody": "<p>Reply text</p>"
}

Generic JSON ​

json
{
  "from": "user@example.com",
  "to": "claim+123@my-warranties.nl",
  "text": "Reply text",
  "html": "<p>Reply text</p>"
}

Features ​

Email Body Cleaning ​

Automatically removes:

  • Quoted text (lines starting with >)
  • Previous email content (text after "On ... wrote:")
  • Email signatures
  • HTML blockquotes

Attachment Support ​

Emails can include:

  • Photos (JPG, PNG, GIF)
  • Documents (PDF)
  • Up to 1 attachment per email
  • Base64 encoded content

Claim ID Extraction ​

The system extracts claim ID from recipient address:

claim+123@my-warranties.nl  →  Claim ID: 123
claim+456@my-warranties.nl  →  Claim ID: 456

Testing ​

Test Webhook Locally ​

bash
# Simulate Resend webhook
php bin/test-resend.php webhook 1 customer@example.com "Test message"

Test Signature Verification ​

bash
php bin/test-resend.php signature-test

Integration Test ​

  1. Create a claim in the app
  2. Send a message as customer
  3. Check supplier receives email
  4. Reply to email
  5. Verify message appears in claim

Troubleshooting ​

Emails Not Sending ​

Check:

  • MAILER_DSN is correct in .env
  • Resend API key is valid
  • Domain is verified in Resend
  • Application logs for errors

Webhooks Not Working ​

Check:

  • Webhook URL is publicly accessible (HTTPS)
  • RESEND_WEBHOOK_SECRET matches Resend dashboard
  • Inbound route is configured in Resend
  • Application logs for errors

Signature Verification Failing ​

Check:

  • RESEND_WEBHOOK_SECRET exactly matches (no extra spaces)
  • Webhook is coming from Resend (check source IP)
  • Timestamp is within 5 minutes
  • Test: php bin/test-resend.php signature-test

Best Practices ​

  • Always use HTTPS in production
  • Verify webhook signatures (don't skip for convenience)
  • Monitor email deliverability in Resend dashboard
  • Set up SPF/DKIM properly for better delivery
  • Test reply flow before going live
  • Handle edge cases (invalid emails, spam, etc.)

API Reference ​

For complete API endpoint documentation, see the API Reference section.

MyWarranties - Warranty Management System

Copyright © 2024-present MyWarranties