Email deliveries

A delivery is one email to one recipient. Transactional deliveries are created by Send email; lifecycle deliveries are created by an enabled sequence. Every endpoint below takes projectId as a query parameter with an API key. The Node.js client @funnelsgrove/emails sends it from the projectId option, and fgrove email from --project-id or FUNNELSGROVE_PROJECT_ID.

Delivery status is queued, sent, failed or unknown. Sent means accepted by the provider, not guaranteed inbox placement.

Send email

Queues a published template for delivery. Follow the email sending policy before sending to your audience.

Scope: email_deliveries:write

Request

POST /email/deliveries
Content-Type: application/json
Idempotency-Key: <unique-key>

Idempotency-Key is required: 1 to 200 characters from A-Z a-z 0-9 . _ : -. Reuse it when retrying the same logical send.

Parameters

Field	Required	Purpose
template	Yes	Slug of a published template.
to	Yes	Recipient address.
variables	Yes	A value per declared template variable: string, number or boolean. Send {} when the template declares none.
cc	No	Up to 10 distinct addresses; may not include to. CC recipients pass the same suppression and velocity checks as to.
attachments	No	At most one PDF up to 5 MiB: { "filename": "<name>.pdf", "contentType": "application/pdf", "contentBase64": "<base64>" }. Attachment bytes are removed from storage after a terminal outcome.
from	No	{ "email", "name"? }. The domain must be a verified sending domain of the project; any local part is allowed. Without name, the domain's sender display name is used. Without from, a verified default sending domain must be active.
replyTo	No	One address; may use an external domain.

Example

curl -X POST "https://sdk-api.funnelsgrove.com/integration/v1/email/deliveries" \
  -H "Authorization: Bearer <project-sdk-secret-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-code-481953" \
  --data '{
    "template": "login-code",
    "to": "person@example.com",
    "variables": { "code": "481953", "expiresInMinutes": 10 },
    "from": { "email": "security@mail.example.com", "name": "Example Security" },
    "replyTo": "support@example.com"
  }'

Response

202 with the delivery receipt:

{ "id": "<delivery-id>", "status": "queued" }

Errors

Status	Meaning
400	The body or Idempotency-Key is invalid, or the variables do not match the template.
404	The template does not exist or is not published.
409	Project sending is paused, no sender is available, or the recipient is suppressed.
429	The recipient's velocity limit was exceeded.
503	Admission is temporarily unavailable; retry with backoff.

Get delivery

Scope: email_deliveries:read

Request

GET /email/deliveries/:deliveryId

Example

curl "https://sdk-api.funnelsgrove.com/integration/v1/email/deliveries/<delivery-id>" \
  -H "Authorization: Bearer <project-sdk-secret-key>"

Response

{
  "id": "<delivery-id>",
  "status": "sent",
  "terminalReason": null,
  "createdAt": "…",
  "updatedAt": "…",
  "sentAt": "…",
  "failedAt": null
}

Errors

Status	Meaning
400	deliveryId is not a UUID.
404	The delivery does not exist in this project.

Update variables

Replaces the variables of a queued lifecycle delivery during its personalization window. For a step with personalizationEnabled, funnelsgrove sends the email.personalization_requested webhook 20 minutes before the due time; call this endpoint after the webhook and before dueAt.

Scope: email_deliveries:write

Request

PATCH /email/deliveries/:deliveryId/variables
Content-Type: application/json

Parameters

Field	Required	Purpose
variables	Yes	A value per declared template variable. Only declared variables with valid types are accepted.

Example

curl -X PATCH "https://sdk-api.funnelsgrove.com/integration/v1/email/deliveries/<delivery-id>/variables" \
  -H "Authorization: Bearer <project-sdk-secret-key>" \
  -H "Content-Type: application/json" \
  --data '{ "variables": { "firstName": "Ada" } }'

Response

{
  "id": "<delivery-id>",
  "status": "queued",
  "variables": { "firstName": "Ada" },
  "subject": "…",
  "html": "…",
  "text": "…",
  "dueAt": "…",
  "updatedAt": "…"
}

Errors

Status	Meaning
400	The variables do not match the template.
404	The delivery does not exist in this project.
409	The delivery is outside its personalization window or has started sending.