Documentation
Menu

API

Add contacts from your site and create drafts from scripts

Create a key under Settings > API keys and send it as Authorization: Bearer <key>. A key acts for its organization only.

Add a contact

POST /api/v1/contacts

bash
curl -X POST https://<your-app>/api/v1/contacts \
  -H "Authorization: Bearer $OXIDT_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newsletter":"weekly","email":"jane@example.com","source":"website","ip":"203.0.113.7"}'
  • newsletter (slug) and email are required. source labels where the signup came from.
  • name and attribs (an object, at most 50 keys) fill {{name}} and {{attr.key}} in emails; new attributes merge into existing ones.
  • Addresses on the organization's blocked domains are refused with 400.
  • resubscribe: true brings back someone who unsubscribed, never someone who bounced or complained.
  • Pass your visitor's IP as ip for a limit of 5 signups per visitor per 10 minutes. Each organization is limited to 600 signups an hour.
  • Answers 201 for a new contact, 200 for an existing one: { id, status, created }. When the newsletter confirms signups, status is pending and inbox may link to the reader's mailbox.

Create a draft

POST /api/v1/campaigns with newsletter, subject, previewText (optional), either html or markdown, and archiveSlug (optional). Answers 201 with { id, url, archiveSlug }. Sending stays a click in the dashboard.

List sent issues

GET /api/v1/campaigns?newsletter=<slug> returns each listed issue's id, subject, previewText, archiveSlug, url (when the archive is on) and sentAt.

Send a transactional email

POST /api/v1/send with newsletter (the from address, reply-to and name come from it), to, subject, previewText (optional), either html or markdown, plus name and data for {{name}} and {{attr.key}}. It goes out right away, untracked, without list headers or footer. Suppressed addresses get 409. Limited to 600 an hour per organization.

Report a bounce

POST /api/v1/bounces with email, type (hard, soft or complaint) and source (optional). Use it from any provider's bounce webhook when you don't send through SES. Hard bounces and complaints suppress the address at once; three soft bounces in a row do too.