v52

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-07-21450373.3 KB
emails

Send a custom email

Send an email from your publication to a list of recipient addresses.

Eligibility:

  • Publications must be approved by Paragraph before they can send custom emails. Ineligible publications receive a 403. Eligibility is managed by Paragraph and is not user-configurable.

Per-recipient filtering:

  • Malformed addresses and known disposable domains are skipped.
  • Addresses that previously unsubscribed from this publication are skipped as suppressed.
  • Skipped recipients are returned in the response; nothing else is delivered to them.

Delivery:

  • body is treated as Markdown and rendered to HTML server-side.
  • Each recipient receives the email individually (not as a BCC blast) with a mandatory unsubscribe footer.
  • Sends are queued asynchronously; a 200 response means recipients were accepted, not delivered.

Caps:

  • Maximum of 10,000 addresses per call (request-level sanity check).
post/v1/emails/send

Request body

subjectstring required

Subject line of the email

bodystring required

Email body. Markdown; rendered to HTML server-side. Max 100KB.

emailsstring[] required

Recipient email addresses (max 10,000). Malformed addresses are returned in skipped with reason: "invalid" rather than rejecting the whole request.

dryRunboolean

If true, run filtering and return the accepted/skipped split without scheduling delivery

Response

Send request accepted

acceptedinteger required

Number of recipients queued for delivery (or that would be queued when dryRun is true)