Sending Email via API

This page provides an example of how to send an email using the NotifiedBy API with curl.

Example using form parameters:

curl -X POST https://api.notifiedby.com/v1/email/send/ -H "Authorization: Api-Key YOUR_API_KEY" \
--form 'recipient="YOU@TESTEMAIL"' \
--form 'subject="email from API"' \
--form 'body="<h1>Email from API</h1><p>This is an <strong>HTML</strong> email body.</p>"' \
--form 'plain_body="This is the plain text version of the email body."'

Example using data parameter:

curl -X POST https://api.notifiedby.com/v1/email/send/ -H "Authorization: Api-Key YOUR_API_KEY" \
-d "recipient=YOU@TESTEMAIL&subject=email from API&body=<h1>Email from API</h1><p>This is an <strong>HTML</strong> email body.</p>&plain_body=This is the plain text version of the email body."

YOU@TESTEMAIL should be set to your email or your customer’s email address.

Unsubscribe placeholder in email content

If your sender is configured for unsubscribe handling, you can place the unsubscribe placeholder directly into the HTML body you send:

<p>If you no longer want product updates you can [[notifiedby:unsubscribe]] at any time.</p>

NotifiedBy replaces [[notifiedby:unsubscribe]] with the real unsubscribe link for that recipient when the email is sent.

The generated anchor includes the CSS class unsubscribe-link so you can apply your own email styling to it.

See Unsubscribe Links and Webhook Handlers for sender configuration and client webhook handling details.

Note

The API is version numbered and the current version is 1. Any breaking changes to the API will use a new version number.

Response

The response from the API for a successful request is a 200 HTTP response with JSON structure like: {“id”:”JDT”} where JDT is an identifier for the email.

Error codes from the API are:

No or invalid API key provided

{"detail":"Authentication credentials were not provided."}

Error for missing parameters

{"recipient":["This field is required."]}

{"body":["This field is required."]}

{"subject":["This field is required."]}

Error when recipient is blocked

{"id":"XXX","error":"Recipient is blocked"}

Note

The API will return a 400 HTTP response if the request is malformed in any way.