API Reference

The Mailcast API allows you to programmatically manage your email aliases, templates, and other resources.

Base URL

All API requests should be made to:

https://api.mailcast.io/v1

Authentication

All API requests require authentication using a Bearer token. Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Tokens are prefixed by mode:

• test_… — test mode. Can send email and manage test templates. Other endpoints return 403.
• prod_… — production mode. Full API access.

The key is the only mode switch; there is no separate test API host.

Test keys may call:

• Send Email — off-org recipients are delivered to the token redirect_email (required when the key is created). Same-org recipients are delivered as requested. The RFC2822 To/Cc headers are unchanged.
• Templates — creates and updates test-only templates. Test keys can send both test and production templates. They cannot modify or delete a production template.

A production key PATCH of a test template promotes it to production. Production keys cannot send a test-only template (403).

Idempotency keys are independent per mode: the same idempotency_key can be used in test and production without colliding.

Delivery webhooks are split by mode. Test sends only reach test webhook endpoints and include "test": true on the payload. Production webhooks never receive test events.

You can generate API tokens in your Mailcast dashboard under the API section.

Response Format

All API responses are returned in JSON format with the following structure:

Success Response

{
  "id": "alias_abc123",
  "match": "support",
  "state": "active",
  "actions": [...],
  "created_at": "2024-01-01T00:00:00.000000Z",
  "updated_at": "2024-01-01T00:00:00.000000Z"
}

Error Response

{
  "error": "error message",
  "details": {
    "field": "validation error message"
  }
}

HTTP Status Codes

• 200 - Success
• 201 - Created
• 204 - No Content
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden (test key used on a production-only endpoint, or a template the key is not allowed to send or change)
• 404 - Not Found
• 422 - Validation Error
• 429 - Rate Limited
• 500 - Internal Server Error

Endpoints

Aliases

Manage email aliases for your domains.

• Create Alias - Create a new email alias
• List Aliases - List all aliases for a domain
• Get Alias - Get details of a specific alias
• Update Alias - Update an existing alias
• Delete Alias - Delete an alias

Alias actions — Add, update, or remove individual actions on an existing alias:

• Add Action - Add an action to an alias
• Update Action - Update an action on an alias
• Delete Action - Remove an action from an alias

Templates

Create templates from MJML or HTML and send them with template_id or user_id plus data. See template variables for how to handle dynamic data.

• Template language - Handlebars-style variables, conditionals, and loops
• Create Template - Create a template from MJML or HTML
• List Templates - List templates for the token domain
• Get Template - Get a template
• Update Template - Update a template
• Delete Template - Delete a template
• Promote Template - Copy a test template to production

Emails

• Send Email - Send an email, optionally using a template