Send a form using the Hushmail API

You can use the Hushmail API to send one of your secure forms to a recipient directly from your own software or workflow.

Request

To create a form instance and email it to a recipient, send a POST request to https://secure.hushmail.com/api/v1/forms/instances. The request body must be valid JSON and include all of the following fields:

• form_identifier: The identifier of the form you want to send. You must own this form, or have it shared with you.
• email_to: The recipient's email address.
• email_subject: The subject line of the email.
• email_body: The message body of the email. Plain text or HTML.

Example request

curl https://secure.hushmail.com/api/v1/forms/instances \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "form_identifier": "raymond-rogers-intake-form",
    "email_subject": "Please complete your intake form",
    "email_to": "alice@example.com",
    "email_body": "<p>Please fill out the attached intake form prior to your first appointment.</p>"
  }'

Response

The API will respond with one of the following status codes:

• 200: The form instance was created and the email was sent.
• 400: The request was invalid. Check for a missing or invalid JSON body, or missing required fields.
• 401: The API key was missing, malformed, or invalid.
• 403: The request was not allowed. Check that you own the form, or have it shared with you.
• 404: The requested endpoint was not found.
• 405: The HTTP method is not allowed for this endpoint. The Allow response header lists the permitted methods.
• 429: Too many requests. Requests are rate-limited. Wait a few seconds and try again.
• 500: An unexpected server error occurred.

Example success response

A successful request returns the identifier of the form instance, the Message-ID of the email, and a status of sent.

{
  "form_instance_identifier": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "message_id": "<abc123@secure.hushmail.com>",
  "status": "sent"
}

Example error response

An unsuccessful request returns an error object with a machine-readable code and a human-readable message describing the problem.

{
  "error": {
    "code": "forbidden",
    "message": "The API key owner does not have access to this secure form."
  }
}