חוזה ה-API
67 נקודות קצה, מתוך openapi.json (גרסה 1.0.0). לנתיבים אין קידומת /api. שגיאות חוזרות כ-JSON עם error_key.
openapi.jsonשרת לשרת
נקרא מהשרת של המערכת המארחת עם מפתח ה-API שלה: Authorization: Bearer <key>.
| שיטה | נתיב | מה הוא עושה |
|---|---|---|
| PUT | /v1/workspaces/{externalId} | Create or update a workspace |
| GET | /v1/workspaces/{externalId} | Read a workspace |
| POST | /v1/workspaces/{externalId}/ui-tokens | Mint a UI token for a signed-in user (15 minutes) |
| POST | /v1/workspaces/{externalId}/suppressions | The host reports a withdrawn marketing consent (scope marketing, idempotent) |
| GET | /v1/workspaces/{externalId}/suppressions | List the workspace's suppressions (who cannot be mailed and why) |
| POST | /v1/workspaces/{externalId}/suppressions/lift | Lift the workspace's marketing suppression after new consent (host only, idempotent). Never lifts an all-scope suppression, a hard bounce, a complaint or an erased address unless consent_source is form or manual with a newer consent_at (H9c) |
| POST | /v1/workspaces/{externalId}/suppressions/search | Find one address in the workspace's suppressions. The address travels in the body, never the URL |
| POST | /v1/workspaces/{externalId}/automated/{key} | Define an automated message and its category (host only) |
| POST | /v1/workspaces/{externalId}/automated/{key}/send | Queue an automated message for one recipient (202 means queued, not sent) |
| GET | /v1/source | The calling host's settings: webhook url and the opt-in events it chose |
| PUT | /v1/source | Choose which opt-in webhook events to receive (replaces the list) |
| POST | /v1/workspaces/{externalId}/campaigns | Create a draft campaign |
| GET | /v1/workspaces/{externalId}/campaigns | List campaigns, newest first |
| GET | /v1/workspaces/{externalId}/campaigns/{id} | Read a campaign |
| PATCH | /v1/workspaces/{externalId}/campaigns/{id} | Update a draft campaign (all fields optional) |
| DELETE | /v1/workspaces/{externalId}/campaigns/{id} | Delete a draft campaign and its pending recipients |
| POST | /v1/workspaces/{externalId}/campaigns/{id}/recipients | Add one chunk of recipients to a draft or scheduled campaign (max 1000 per call; repeating a chunk is harmless) |
| POST | /v1/workspaces/{externalId}/campaigns/{id}/schedule | Schedule a draft campaign (send now or at send_at). The scheduler starts it within a minute of scheduled_at |
| POST | /v1/workspaces/{externalId}/campaigns/{id}/cancel | Cancel a draft, scheduled, testing or sending campaign. Pending and queued recipients end skipped / campaign_cancelled at once; a row already being handed to SES finishes |
| POST | /v1/workspaces/{externalId}/designs/{id}/test-send | Test-send a design to up to 5 addresses |
| POST | /v1/workspaces/{externalId}/designs/{id}/preview | Preview a design or a campaign's email (host key; same body and answer as the UI route) |
| POST | /v1/workspaces/{externalId}/campaigns/{id}/test-send | Test-send a campaign's design and subject to up to 5 addresses (the campaign itself is not changed) |
| GET | /v1/workspaces/{externalId}/deliveries/{id} | Read one delivery with its events |
| GET | /v1/workspaces/{externalId}/campaigns/{id}/deliveries | Recipient activity of a campaign |
| GET | /v1/workspaces/{externalId}/domains | List the workspace's sending domains with DNS records (read-only; same list as GET /v1/ui/domains) |
| GET | /v1/workspaces/{externalId}/campaigns/{id}/report | Campaign report: counts, rates, links |
| GET | /v1/workspaces/{externalId}/campaigns/{id}/timeline | Campaign timeline |
| GET | /v1/workspaces/{externalId}/automated/{key}/report | Automated message report |
| GET | /v1/workspaces/{externalId}/reports/automated | All automated message reports |
| GET | /v1/workspaces/{externalId}/reports/summary | Workspace summary report |
| GET | /v1/workspaces/{externalId}/usage | Emails sent per day and month |
| PUT | /v1/workspaces/{externalId}/campaigns/{id}/ab-test | Define or replace the A/B test of a draft campaign |
| DELETE | /v1/workspaces/{externalId}/campaigns/{id}/ab-test | Remove the A/B test of a draft campaign |
| POST | /v1/workspaces/{externalId}/campaigns/{id}/ab-test/winner | Pick the A/B winner (host) |
| GET | /v1/workspaces/{externalId}/deliverability | Deliverability: domain health, rates, warm-up, pause state |
| POST | /v1/workspaces/{externalId}/orders | Report an order; the Mailer attributes it to the contact's last click within attribution_window_days (idempotent per order_id). No email or contact id is stored |
| POST | /v1/workspaces/{externalId}/countdown-urls | Create a signed countdown image URL (/t/{token}.png) for a design. No contact, address or workspace in the token |
| POST | /v1/workspaces/{externalId}/erasures | Right to erasure for one address in the workspace (host key only, idempotent, audited by keyed hash) |
דפדפן (טוקן UI)
נקרא מהמסכים של המערכת המארחת עם טוקן UI ל-15 דקות שהיא מנפיקה.
| שיטה | נתיב | מה הוא עושה |
|---|---|---|
| GET | /v1/ui/domains | List sending domains with DNS records |
| POST | /v1/ui/domains | Add a sending domain (unique across all workspaces) |
| POST | /v1/ui/domains/{id}/check | Check a domain now |
| DELETE | /v1/ui/domains/{id} | Remove a domain and its SES identity |
| GET | /v1/ui/designs | List designs (summaries, no html) |
| POST | /v1/ui/designs | Create a design |
| GET | /v1/ui/designs/{id} | Read a design |
| PUT | /v1/ui/designs/{id} | Update a design (all fields optional) |
| DELETE | /v1/ui/designs/{id} | Delete a design |
| POST | /v1/ui/designs/{id}/preview | Preview a design as a real send would render it (nothing is sent or stored) |
| POST | /v1/ui/images | Upload an image for the editor (multipart, field file; jpg jpeg png gif webp, 5 MB) |
| GET | /v1/ui/automated | List automated messages |
| PATCH | /v1/ui/automated/{id} | Configure an automated message (never its key, name or category) |
| GET | /v1/ui/suppressions | List the workspace's suppressions |
| POST | /v1/ui/suppressions/search | Find one address in the workspace's suppressions (body, not URL) |
| GET | /v1/ui/campaigns | List campaigns (UI token, reports.view; same JSON as the host route) |
| GET | /v1/ui/campaigns/{id} | Read a campaign (UI token, reports.view) |
| POST | /v1/ui/designs/{id}/test-send | Test-send a design to up to 5 addresses (UI token, designs.test_send) |
| GET | /v1/ui/deliveries/{id} | Read one delivery with its events (UI token, reports.view) |
| GET | /v1/ui/campaigns/{id}/deliveries | Recipient activity of a campaign (UI token, reports.view) |
| GET | /v1/ui/campaigns/{id}/report | Campaign report (UI token, reports.view) |
| GET | /v1/ui/campaigns/{id}/timeline | Campaign timeline (UI token, reports.view) |
| GET | /v1/ui/automated/{key}/report | Automated message report (UI token, reports.view) |
| GET | /v1/ui/reports/automated | All automated message reports (UI token, reports.view) |
| GET | /v1/ui/reports/summary | Workspace summary report (UI token, reports.view) |
| GET | /v1/ui/usage | Emails sent per day and month (UI token, reports.view) |
| GET | /v1/ui/deliverability | Deliverability (UI token, domains.manage) |
| POST | /v1/ui/countdown-urls | Create a signed countdown image URL (/t/{token}.png) for a design. No contact, address or workspace in the token |
ציבורי
נקרא על ידי AWS; מאומת בחתימה.
| שיטה | נתיב | מה הוא עושה |
|---|---|---|
| POST | /sns | SES events through SNS (signature-verified; body is JSON sent as text/plain) |