Payload Emails

Some of the most important email you send is about something Paminga has never heard of. An order number. A shipping ETA. A one-time link. The copy and the design belong to your marketing team, but the values only exist in your systems at the moment the email goes out.

A Payload Email is built for exactly that. You drop tokens into the email and name the keys yourself — no field to create first, no object to define, no schema to agree on. Then you send the email over the API with a JSON payload carrying those keys, and Paminga merges the values in.

Marketing owns how it looks. Your systems own what it says.

Creating a Payload Email

Choose API Payload as the Content Source when you create the email.

That choice is permanent — an email's Content Source can't be changed afterward — so pick it at creation rather than converting an existing email.

Everything else about the email works normally: brand kits, layout, personalized fields, images, links. Payload tokens sit alongside your Contact and Account tokens rather than replacing them.

Adding Payload Tokens

Click into any text, open Personalize with Tokens, and choose Payload as the token source. You'll get two fields:

• Payload Key — the name you'll use in your API call. orderNumber, trackingUrl, whatever your systems already call it.
• Default Value — what renders if your payload doesn't include that key.

The Payload source only appears on Payload Emails. On any other email there's nothing to supply the values, so offering it would only lead you somewhere that quietly does nothing.

Nested Keys

A dot reads into a nested object. A token keyed order.number is filled by:

{ "order": { "number": "A-10432" } }

Use whichever shape your system already produces — you don't have to flatten anything on the way in.

One Key Can't Be Two Shapes

A dot makes a key a path, so test and test.subTest can't both live in one email. The first asks for text where the second asks for an object, and no payload satisfies both — one of the two tokens would render its default forever. The builder refuses the second key and tells you which existing one it collides with.

Reusing the same key is fine, and often what you want: an order number in the body and again inside a link is one value filling both tokens.

Default Values Matter Here

With ordinary personalization, a missing first name is cosmetic. With a payload, a missing key means the value your recipient actually needed isn't there.

There's deliberately no schema to validate against — that's what makes these keys yours to name — so nothing catches a typo before the send. orderNumber in the email and order_number in your payload will not match, and the default renders instead.

Give every token a default that reads acceptably on its own. "your recent order" beats a blank space.

The Payload Tab

Open a Payload Email and you'll find a Payload tab in the left panel, where Variants normally sits. It replaces Variants because these emails go to one person at a time with one payload — there's nothing for an A/B split to vary.

The tab shows the exact request for this email: the API route, and a complete JSON body with every key the email currently reads, ready to copy. It updates as you add and remove tokens, so it always describes the email in front of you.

tip

Hand the Payload tab's contents to whoever is writing the integration. It's the whole contract — route, shape, and key names — in one place, and it can't drift from the email because it's generated from it.

Sending

Send a Payload Email by posting to the API, the same way you'd trigger an Abandoned Cart automation.

The API is the only way one of these goes out. A Payload Email doesn't appear in the email picker on a workflow, drip, or send action — none of those paths carry a payload, so the email would go out with every token showing its default.

Send It in the builder doesn't set up a segment send either. It opens the request your systems need to make — the same route and JSON body the Payload tab shows — so you can hand it straight to whoever is writing the integration. Send Test works normally; a test send has no payload, which makes it a good look at what your default values actually render as.

Endpoint

https://api.paminga.com/api/email/send

If your account is hosted in the EU, use https://api.eu.paminga.com instead. The Payload tab in the builder always shows the right host for your account.

Authentication

Pass an OAuth token as a "bearer" token:

headers: {
  'Content-Type': 'application/json',
  Authorization: 'Bearer {YOUR_AUTH_TOKEN}',
}

JSON Payload

{
  "email_id": 2647,
  "customer": {
    "email": "dana@example.com",
    "firstName": "Dana"
  },
  "payload": {
    "orderNumber": "A-10432",
    "trackingUrl": "https://example.com/track/A-10432"
  }
}

Three parts:

• email_id — which email to send. You'll find it in the Payload tab, and in the URL when the email is open.

• customer — who to send it to. email is the only required field, and it's also how Paminga finds the contact, creating one if it doesn't exist yet. Everything else is optional: firstName, lastName, workPhone, mobilePhone, homePhone, address, city, postalCode, country. Send city and country as names — "Denver", "United States" — and spell them the way you'd expect to read them back: they're matched against Paminga's reference tables, and a near-miss is recorded as written rather than corrected to the nearest match. This is the same block the Abandoned Cart trigger takes, so an existing integration already speaks it.

  Any key outside that list is ignored rather than rejected — send phone instead of workPhone and it's dropped without complaint.

• payload — your keys and values.

A successful call returns 202 along with payload_keys_accepted and payload_keys_ignored. Check payload_keys_ignored when something doesn't appear in a delivered email — a key listed there was sent but wasn't usable.

Every Call Sends

Each call sends its own email with its own payload. Three orders from the same customer in an hour produce three emails, each describing the right order.

That's the reason this is a direct send rather than a workflow entry. A workflow is built to run a person through a journey once, so a second order for the same customer would be turned away — correct behavior for a journey, wrong for a receipt.

When a Call Is Refused

Refusals come back on the call itself, not silently afterward:

Response	Meaning
401	Missing or invalid credentials.
404	No such email, or it belongs to another account.
422	The email isn't a Payload Email, isn't published, or the payload is missing or unusable.

A 422 for a missing payload includes required_keys — the keys that email actually reads — so the call tells you what it wanted.

Values, and What Happens to Them

Payload values are single values: text, numbers, true/false. A list of line items isn't something a token can render — for repeating content like carts and product grids, use a dynamic composition element instead.

Values are cleaned on arrival. Anything that isn't a single value is dropped and the token's default renders. Very long values are truncated. This keeps an unexpected payload from turning into a broken email.

Payload values are never stored on the contact. They're merged into that one email and nothing else. A contact's record is unchanged by a Payload Email send.

Links

A payload token works inside a link, with one wrinkle worth knowing.

Put the token in the path or query and the link is tracked normally:

https://example.com/orders/{orderNumber}

Use a token as the entire URL and the link still works, but Paminga can't click-track it — the destination is different for every recipient, so there's nothing stable to attribute a click to. Nothing in the builder warns you about this, so it's worth knowing before you build a report around those clicks.

If click tracking matters, keep a real domain in the URL and let the token fill in the rest.

Payload Emails and Unsubscribes

A Payload Email follows the same rules as any other email. If the recipient is unsubscribed, they won't receive it unless the email is marked transactional — see Mass Transactional Emails for what that means and when it's appropriate.

Worth thinking about before you send receipts: an order confirmation is a reasonable transactional email. A "you might also like" follow-up isn't, no matter what triggered it.

note

Payload Emails are an internal Paminga feature for now, and not yet available on customer accounts. There's no per-account switch to turn them on — general availability will be announced when the send path opens up.