Frequently Asked Question

All Categories » Arkane API / Generate Framework

Generate - Construct and Send an email based on provided payload

Last Updated 7 days ago

Generate API

Overview

The Generate API is a versatile tool for creating and sending emails with optional PDF attachments. It uses predefined templates, allows for dynamic content substitution, and supports both plain text and HTML emails.

Version

1.003

Endpoint

/docugen/generate.php

Authentication

This API requires authentication using an API key. The key should be passed in the HTTP_X_API_KEY header.

Request Format

The API accepts a JSON payload with the following structure:

Required Fields:

Field	Type	Description
function	string	"email" or "pdf" - Specifies the primary function to perform
template	string	The name of the template to use
email.to	string	Recipient email address
email.from	string	Sender email address
email.subject	string	Email subject
email.html	boolean	Whether to send as HTML email

Optional Fields:

Field	Type	Description
email.cc	string	Carbon copy recipients (comma-separated)
email.bcc	string	Blind carbon copy recipients (comma-separated)
attachment.base64	string	Base64 encoded attachment
attachment.filename	string	Filename for the attachment
attachment.type	string	MIME type of the attachment
pdf.header	string	Content for PDF header (only used when function is "pdf")
pdf.footer	string	Content for PDF footer (only used when function is "pdf")
email.body	string	Email body when attaching PDF (only used when function is "pdf")

Response

The API returns a JSON object with the following structure:

Field	Type	Description
status	string	"success" if the operation was successful, "error" otherwise
message	string	A description of the result or error
function	string	The function that was performed (only if successful)
template	string	The name of the template used (only if successful)
fields	object	The input fields used (only if successful)
failed_fields	array	List of fields that failed substitution (only if error)

Example Request


$payload=array(
    "function"=>"email",
    "template"=>"test_notification",
    "email.to"=>$EMAIL,
    "email.from"=>"noreply@gen.uk",
    "email.subject"=>"Test Notification",
    "email.html"=>true,
    "email.cc"=>"",
    "email.bcc"=>"",
    "heading"=>"TEST",
    "name"=>$NAME,
    "message1"=>"This is Message 1",
    "message2"=>"This is Message 2",
    "footer"=>"This is the footer"
);

In our template, test_notification, we're using {{heading}}, {{name}, {{message1}}, {{message2}} and {{footer}} which we're providing substitutions for in this request. This PHP array can then be converted to JSON and used in the POST.

Example Response (Success)


{
  "status": "success",
  "message": "Email sent successfully",
  "function": "email",
  "template": "gen_notification",
  "fields": {
    "email.to": "recipient@example.com",
    "email.subject": "Test Email"
    // ... other fields
  }
}

Example Response (Error)


{
  "status": "error",
  "message": "Failed to substitute all fields",
  "failed_fields": ["customer.name", "order.number"]
}

Error Handling

Invalid JSON payload: {"status": "error", "message": "Invalid JSON payload"}
Template not found: {"status": "error", "message": "Template not found"}
Missing required parameters: {"status": "error", "message": "Missing required parameters"}
Email sending failure: {"status": "error", "message": "Email could not be sent. Mailer Error: [error details]"}
Field substitution failure: {"status": "error", "message": "Failed to substitute all fields", "failed_fields": [...]}

Notes

The API supports dynamic content substitution using {{field_name}} syntax in templates.
System fields like date and time can be used with {{system.field_name}} syntax.
When function is "pdf", the API generates a PDF and attaches it to the email.

Security

The API key should be kept secure and not exposed in client-side code.
Input validation is performed on the JSON payload and individual fields.

Limitations

Only one attachment can be included per email.
The API doesn't support custom PDF sizes or orientations (fixed to A4 portrait).
ALL Substitutions MUST be provided.