Updates an email's fields. Only provided fields change. The content field accepted depends on the email's format: an email that renders a Page accepts `page_id`; an email that renders embedded structured content accepts `viewport_data`. Emails in the content_blocks format cannot be edited through this API. If recipient_emails is supplied, typo-domain addresses are stripped.
AuthorizationRequiredBearer <token>API key as Bearer token
In: header
application/jsonRequiredsubjectstringThe email subject.
recipient_emailsarray<string>Recipient email addresses. Note that if sync_event_recipients is true,
this will not include event attendees until send time.
recipient_phonenumbersarray<string>Unused.
event_refsarray<string>IDs of events whose attendees will be added to the recipients at send time.
timeslot_refsarray<string>IDs of multi-day event timeslots whose attendees will be added to the recipients at send time.
segment_refsarray<string>IDs of segments whose members will be added to the recipients at send time, with each member's segment columns available as smart values (mail merge). The composer currently imports a single segment.
footer_imagestringURL of the image shown in the email footer.
reply_to_emailstringReply-to address. Falls back to a system address when unset.
display_namestringSender label shown on the "From" line.
viewport_dataobjectStructured site-builder content — the AI-editable representation of the email body. Compose the email by emitting a viewport_data tree (pages → layouts → HTML blocks); do NOT supply pre-rendered HTML via 'body'. The send flow renders viewport_data into HTML automatically. Most emails are a single page with a sequence of one-column layouts. Use two-column for side-by-side content, and event-block when promoting a specific event (give it the event id's url, name, and date — never embed event details in an HTML column). Layout ids must be unique within the page; "page:1", "layout:1", "layout:2", ... is the simplest scheme. Pick cardHeight=100 unless the design calls for taller rows. Event link URLs (whether on event-block.event.url or inside an HTML in a one-column / two-column 'content' / 'columns' string) MUST use the canonical format: https://3common.com/event/{event_id} where {event_id} is the id from the email's event_refs array. Don't invent ad-hoc URLs — recipients click these to land on the real event page, and referral tracking + unsubscribe substitution rely on the canonical host. Do NOT include {{unsubscribeUrl}} or any other {{…}} substitution placeholder anywhere in viewport_data. The api-server's email template renders the unsubscribe footer itself; emitting it in the body produces a duplicated, broken link. Styling beyond what TipTap exposes (custom font colors, font families, font sizes outside the h1-h6 progression, background colors) is NOT supported — the editor has no UI for it and round- trips will strip it. Use semantic tags (h1-h6 for size, strong/em for emphasis) instead of inline style.
page_idstringID of the Page this email renders.
sync_event_recipientsbooleanIf true, scheduled sends re-sync recipients from the linked events at send time.
attachmentsarray<object>File attachments included with the email.
activity_synced_atnumberEpoch ms when the activity feed was last synced from Sparkpost + orders.
idRequiredstringEmail id, discoverable via list_emails