Trigger an Email

post

https://triggeremail-api.hldapps.com/api/trigger-email

Sends an email based on a pre-configured campaign template. You must provide a valid NPI, Campaign ID, and an authorization Token. Optional fields allow for test sends and dynamic overrides of sender name, sender email username, reply-to address, subject line, and preheader.

Authentication

Include the API Key in the Authorization header of all API requests:

Authorization: <YOUR_API_KEY>

🔑
To generate the API Key follow the instructions outlined here. The API Key is required for all authenticated requests. Make sure to keep it secure and do not share.

Sample Request Payloads

{
  "NPI": "1987654321",
  "CampaignId": "123",
  "Token": "1A23B456-1111-2222-3333-A12B3C4D5E6F",
  "Custom1": "P-12345"
}

{
  "NPI": "9876543210",
  "CampaignId": "2345",
  "Token": "A123B456-1111-2222-3333-1A2B3C4D5E6F",
  "IsTest": true,
  "TestEmail": "[email protected]",
  "Custom1": "Q2 Newsletter Preview",
  "Custom2": "Internal Test"
}

{
  "NPI": "1987654321",
  "CampaignId": "7891",
  "Token": "A123B456-1111-2222-3333-1A2B3C4D5E6F",
  "FromName": "Dr. Jane Smith",
  "FromEmailUsername": "jane.smith",
  "ReplyTo": "[email protected]",
  "SubjectLine": "Your Q2 Newsletter",
  "Preheader": "Check out our latest updates"
}

👍
When the API request is successful and the triggered email is successfully queued, a 'requestId' is returned in the response. ThisrequestIdcan be used to track and retrieve all engagement data related to the request.

Body Params

Details for the email to be triggered. npi, campaignId, and token are mandatory.

npi

string

required

Provide a valid target HCP (Healthcare Provider) NPI (National Provider Identifier).

campaignId

number

required

The pre-configured Campaign ID for the desired email template to deploy.

token

string

required

Provide the secret token authorized for the specified campaign.

isTest

boolean

(Optional) Set to true to send a test email. If true, the testEmail field becomes required. Defaults to false if not provided.

testEmail

string

(Optional) Email address to send test emails to when isTest is true. This field is required if isTest is set to true.

fromName

string

(Optional) Override the sender display name for this email. Maximum length: 500 characters.

fromEmailUsername

string

(Optional) Override the local part of the sender email address (no domain allowed). Maximum length: 500 characters (including domain parts).

replyTo

string

(Optional) Override the reply-to email address. Must be a valid email address. Maximum length: 500 characters.

subjectLine

string

(Optional) Override the email subject line. Maximum length is configurable via application settings (current value: 1000 characters).

preheader

string

(Optional) Override the email preheader text. Maximum length is configurable via application settings (current value: 1000 characters).

Custom1

string

(Optional) Custom passthrough or merge tag field. This can be used for dynamic content in the email template (e.g., a meeting date, a personalized greeting).

Custom2

string

(Optional) Additional custom passthrough or merge tag field for more dynamic content (e.g., a specific product name, a discount code).

Responses

Authentication

To generate the API Key follow the instructions outlined here. The API Key is required for all authenticated requests. Make sure to keep it secure and do not share.

Sample Request Payloads

When the API request is successful and the triggered email is successfully queued, a 'requestId' is returned in the response. ThisrequestIdcan be used to track and retrieve all engagement data related to the request.

200Success. The email trigger request was accepted and processed. The specific outcome (e.g., queued, suppressed) is detailed in the response body.

400Bad Request. The request was malformed or contained invalid/missing parameters. The message field provides specific details about the error.

401Unauthorized. The API key (Authorization header) is missing, invalid, or not authorized for this operation.

403Forbidden. The authenticated user does not have permission to perform this action, typically due to an invalid campaign or campaign token mismatch.

422Unprocessable Entity. The request was well-formed but contains semantic errors or invalid data that prevent it from being processed. The message field provides specific details about the issue.

429Too Many Requests: The user has sent too many requests in a given amount of time (rate limiting). This error indicates the server is limiting the number of requests allowed from a user or client in order to prevent abuse or overload

500Internal Server Error. An unexpected error occurred on the server. Retrying the request later may be successful. If the problem persists, contact support.

503Service Unavailable. The service is temporarily unavailable, likely due to maintenance or overload. Please retry the request after a short delay.

When the API request is successful and the triggered email is successfully queued, a 'requestId' is returned in the response. This`requestId`can be used to track and retrieve all engagement data related to the request.