Redstone API Documentation

1. Authenticate the request. Add the assigned API key to the endpoint query string.
2. Send a JSON or XML object. Include every required core field and each field required by the selected job type.
3. Provide remote files. Every order requires at least one downloadable data file.
4. Use a unique order ID. An id may only be used once per authenticated company.

Send requests to https://redstonemail.com/apis/createOrder?API=YOUR_API_KEY using POST. Your assigned API key is provided in the API query parameter and identifies the company that owns the order. JSON requests should use Content-Type: application/json; XML requests should use application/xml, text/xml, or another content type containing xml. Standard form submissions and URL-encoded POST bodies are also parsed.

A single seed object or an array of seed objects is accepted. Unknown fields inside a seed record are rejected.

Test orders are stored with api_test enabled. Their names are prefixed with API Test: unless that prefix is already present.

A successful order creation returns HTTP 201 Created. Production responses confirm the client-supplied order identifier. Sandbox responses additionally return the generated Redstone job number, the api_test flag, and an internal order URL so the test order can be reviewed.

{
    "success": true,
    "environment": "production",
    "message": "Production order created successfully.",
    "data": {
        "ext_id": "CLIENT-ORDER-10025"
    }
}

{
    "success": true,
    "environment": "sandbox",
    "message": "Sandbox order created successfully.",
    "data": {
        "job_id": "13761",
        "ext_id": "CLIENT-ORDER-10025",
        "api_test": true,
        "url": "https://development.redstonemail.com/orders/view/6a6cf20f4fc07ee14b8b4567"
    }
}

{
    "success": false,
    "environment": "production",
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "The production order could not be created because of an internal error.",
        "reference_id": "api_64f0000000000.00000000"
    }
}

{
    "success": false,
    "environment": "production",
    "error": {
        "code": "EMPTY_REQUEST",
        "message": "The production request body is empty or missing."
    }
}

• Unknown top-level order fields are rejected.
• lightning_id is optional and requires the authenticated client to be enabled for Lightning.
• A submitted lightning_id must resolve to an existing Lightning configuration available to that client.
• Remote files must use public HTTP or HTTPS URLs.
• File URLs may not contain embedded usernames or passwords.
• Local, private, and reserved file destinations are rejected.
• File URLs using schemes other than HTTP or HTTPS are rejected.

1. Normalize the authenticated client and request payload.
2. Assign the order to the company associated with the authenticated API key.
3. If lightning_id is supplied, verify the authenticated client is Lightning-enabled and verify the referenced Lightning configuration exists and is available to that client.
4. Resolve test or production status.
5. Validate allowed fields and job-specific requirements.
6. Reject a duplicate id for the authenticated company.
7. Validate and download all remote files.
8. Build the internal order and determine its initial status.
9. Save the order and generate the Redstone job number.
10. Store the downloaded files in GridFS.
11. Update the order with its available file icons and return the completed order to the controller.

• Unsupported top-level fields are rejected.
• A submitted lightning_id is rejected unless the authenticated client is Lightning-enabled and the referenced Lightning configuration exists and is available to that client.
• All missing required fields are identified during service validation.
• A duplicate client order ID is rejected before file download.
• Malformed booleans are rejected instead of being silently converted.
• Invalid job-specific fields are rejected before order creation.
• If job-number generation fails, the service attempts to remove the newly created order.
• If file storage fails, the service attempts to remove the order and returns the storage error.
• Temporary downloaded files are removed after success or failure.