Build your first Mage Intake integration

Endpoint Structure

Every form has a unique submission URL:

https://api.mageintake.com/submit/<form-id>

Request Format

Send a POST request with a JSON body:

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "message": "Hello!"
}

Response Format

Successful submissions return HTTP 200 with:

{
  "success": true,
  "message": "Submission received"
}

Supported Field Types

• Text fields
• Email fields
• Number fields
• Textarea fields
• Dropdown menus
• Checkboxes
• Radio buttons

Validation Rules

• Required fields with custom error messages
• Minimum and maximum length
• Regular expression patterns
• Type-based validation (email format, numeric ranges)

Dashboard Features

• Clean submission list with full field data
• Search and filter by any field value
• Export to CSV or JSON at any time
• Email notifications for new submissions

Submission Data

Each submission record includes:

• Timestamp of submission
• All submitted field values
• Submitter IP address
• User agent string

Authenticated Requests

Include your write-only key in the Authorization header:

curl -X POST https://api.mageintake.com/submit/<form-id> \
  -H "Authorization: Bearer <write-key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"jane@example.com"}'

Domain Restrictions

• Allowlist specific origins for each endpoint
• Blocks submissions from unauthorized domains
• Protects against external abuse

Rate Limiting

• Per-endpoint submission limits
• Per-IP throttling
• Automatic — no configuration needed

Write Keys

• Safe to embed in client-side JavaScript
• Can only submit data — cannot read submissions
• Scoped per form endpoint

Read Keys

• Server-side only — never expose publicly
• Used to fetch submission data via API
• Cannot submit new data

Common Status Codes

• 400 Bad Request — the submission failed validation
• 401 Unauthorized — the write key is missing or invalid
• 403 Forbidden — the request came from a domain not on the endpoint's allowlist
• 429 Too Many Requests — the endpoint's rate limit was exceeded
• 500 Internal Server Error — an unexpected error occurred

Error Body

Error responses include a JSON body describing what went wrong:

{
  "success": false,
  "error": "Validation failed",
  "fields": {
    "email": "Must be a valid email address"
  }
}

Basic HTML Form

<form id="contact-form">
  <input type="text" name="name" placeholder="Name" required>
  <input type="email" name="email" placeholder="Email" required>
  <textarea name="message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>

JavaScript Submission

document.getElementById('contact-form')
  .addEventListener('submit', async function(e) {
    e.preventDefault();

    const data = Object.fromEntries(new FormData(this));

    const res = await fetch(
      'https://api.mageintake.com/submit/<form-id>',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer <write-key>'
        },
        body: JSON.stringify(data)
      }
    );

    const result = await res.json();
    console.log(result); // { success: true }
  });