How to Forward Email to an API Endpoint

Overview

Many systems still communicate via email — supplier invoices, booking confirmations, shipping alerts, lead notifications. But your application speaks HTTP. Forwarding email to an API endpoint bridges this gap: every inbound email triggers an HTTP POST to your API, carrying the full parsed email content as a JSON body.

This is fundamentally different from email forwarding (which sends the email to another mailbox) or email notifications (which trigger a simple ping). With JsonHook's email-to-API forwarding, your endpoint receives the complete parsed message — sender, subject, body, headers, attachments metadata — in a single structured JSON request that your API can process immediately.

Typical applications of email-to-API forwarding include:

• Creating CRM records when lead emails arrive
• Triggering order processing when confirmation emails arrive from suppliers
• Posting support tickets to your helpdesk API when customers email your support address
• Running classification or NLP pipelines on incoming email content

Prerequisites

You will need:

• A JsonHook account with an API key
• An API endpoint that accepts POST requests with Content-Type: application/json
• The endpoint must be publicly accessible over HTTPS (not localhost)

For local development, use a tunnel tool such as ngrok or Tunnelmole to expose your local server to the internet. Run:

ngrok http 3000

This gives you a temporary HTTPS URL you can use as your JsonHook webhook target during development.

Step-by-Step Instructions

Follow these steps to forward inbound email to your API:

1. Identify or create your API endpoint. This is the route in your application that will receive the email data. For example: https://api.yourapp.com/inbound/email.
2. Create a JsonHook inbound address pointed at your API endpoint:

   curl -X POST https://api.jsonhook.com/v1/addresses   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"webhookUrl": "https://api.yourapp.com/inbound/email", "label": "API forwarding"}'

3. Note the returned email address and secret. The address (e.g. [email protected]) is what email senders will use. The secret is used for HMAC verification.
4. Configure email sources to send to your JsonHook address. Update any systems, forms, or forwarding rules that currently deliver email to a mailbox to instead send to your JsonHook address.
5. Implement HMAC verification in your API handler to ensure only JsonHook can deliver to your endpoint.
6. Process the JSON payload in your API handler — create database records, call downstream services, trigger notifications, etc.

Code Example

A minimal Go HTTP handler that receives a forwarded email and creates a support ticket:

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "io"
    "net/http"
    "os"
)

type EmailPayload struct {
    Email struct {
        From     string `json:"from"`
        Subject  string `json:"subject"`
        TextBody string `json:"textBody"`
    } `json:"email"`
}

func handleEmailForward(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)

    sig := r.Header.Get("X-JsonHook-Signature")
    mac := hmac.New(sha256.New, []byte(os.Getenv("JSONHOOK_SECRET")))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    if sig != expected {
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }

    var p EmailPayload
    json.Unmarshal(body, &p)

    createTicket(p.Email.From, p.Email.Subject, p.Email.TextBody)
    w.WriteHeader(http.StatusOK)
}

func main() {
    http.HandleFunc("/inbound/email", handleEmailForward)
    http.ListenAndServe(":8080", nil)
}

Common Pitfalls

These mistakes are commonly made when forwarding email to API endpoints:

• Performing slow operations synchronously. If your API endpoint calls a slow downstream service (database write, third-party API), it may not respond within JsonHook's 10-second timeout. Move slow work to a background queue and return 200 immediately.
• Not validating the Content-Type header. JsonHook always sends application/json, but add this check as a safeguard against accidental or malicious non-JsonHook requests reaching your endpoint.
• Forgetting to handle retried deliveries. JsonHook retries on non-2xx responses. Build idempotency into your handler using the X-JsonHook-Delivery-Id header so retries do not create duplicate records.
• Exposing your endpoint without authentication. Even with HMAC verification, consider placing your webhook endpoint behind a rate limiter to prevent abuse.
• Not logging raw payloads during development. Log the full request body during initial integration — email payloads vary widely and you may encounter unexpected fields.