Subscribe Forms

Add a signup form to your website or landing page to grow your subscriber list. MailJawn provides a public endpoint that accepts form submissions without requiring API key authentication.

The Subscribe Endpoint

POST /api/v1/projects/{project_id}/subscribe/

No authentication required — your app's UUID acts as implicit authorization.

Parameters

Parameter	Required	Description
email	Yes	Subscriber's email address
name	No	Display name
tag	No	A tag to apply to the subscriber (e.g., "website", "landing-page")
response_type	No	"json" (default) or "redirect"
redirect_url	No	URL to redirect to after subscription (required when response_type is "redirect")
website	No	Honeypot field — see Bot Protection

Content Types

The endpoint accepts both JSON and form-encoded data:

• application/json — for JavaScript fetch/AJAX calls
• application/x-www-form-urlencoded — for standard HTML form submissions

HTML Form Example

<form action="https://api.mailjawn.com/api/v1/projects/YOUR_PROJECT_ID/subscribe/"
      method="POST">
    <input type="email" name="email" placeholder="you@example.com" required>
    <input type="text" name="name" placeholder="Your name">
    <input type="hidden" name="tag" value="website">
    <input type="hidden" name="response_type" value="redirect">
    <input type="hidden" name="redirect_url" value="https://yoursite.com/thanks">

    <!-- Honeypot: hide this from real users -->
    <div style="display:none">
        <input type="text" name="website" tabindex="-1" autocomplete="off">
    </div>

    <button type="submit">Subscribe</button>
</form>

Response Modes

JSON Mode (Default)

Returns a JSON response — ideal for AJAX/fetch calls:

Success (200):

{"status": "subscribed", "email": "user@example.com"}

Error (400):

{"error": "A valid email address is required."}

Redirect Mode

Set response_type to "redirect" and provide a redirect_url. After processing:

• Success — 302 redirect to your redirect_url
• Error — 302 redirect to your redirect_url with an ?error=invalid_email query parameter

Tip

Redirect mode works great for static sites that can't handle JSON responses. Your thank-you page can check for the error query param to show an appropriate message.

Bot Protection

The website field is a honeypot. Real users never see it (it's hidden with CSS), but bots filling out every field will populate it. When the honeypot is filled, MailJawn silently returns a success response without creating the subscriber.

<!-- Hide from real users with CSS -->
<div style="display:none">
    <input type="text" name="website" tabindex="-1" autocomplete="off">
</div>

Rate Limiting

The subscribe endpoint is rate-limited to 10 requests per minute per IP address. This prevents abuse without affecting normal signups.

If the limit is exceeded, the API returns a 429 Too Many Requests response.

Welcome Automations

Subscribers added through forms always trigger welcome automations (if one is configured and active for your app). There is no option to suppress this — people signing up through a form are genuinely new and should receive your welcome series.

Suppression Handling

If a submitted email is on your app's suppression list (e.g., from a previous hard bounce), the endpoint returns a success response but does not create the subscriber. This prevents revealing suppression status to the form submitter.

Integration with Automation Tools

The subscribe endpoint works with any tool that can send HTTP POST requests. However, for richer data (custom fields, device info, multiple tags), use the authenticated identify endpoint instead.

Note

The subscribe endpoint is intentionally simple — email, name, and one tag. For advanced subscriber creation with custom fields, multiple tags, and device context, use the /identify endpoint with an API key. See Integrations > REST API.

Webhook Integrations (PostHog, Zapier, n8n, Make.com)

For syncing subscribers from analytics platforms, CRMs, or payment providers, MailJawn's /identify endpoint is the better choice. It supports:

• Custom fields
• Multiple tags
• Device context
• Automation control (trigger_automations: true/false)

Configure your webhook tool to POST to:

POST /api/v1/projects/{project_id}/subscribers/identify/
Authorization: Bearer mj_xxxxxxxx
Content-Type: application/json

See Integrations > Webhooks for detailed setup guides for PostHog, Zapier, and n8n.

---

See also: Integrations > REST API for the full endpoint reference.