Aiosis Emails

API documentation

Send transactional email, manage contacts and lists, run campaigns, and read delivery and engagement events — over a REST API scoped to your account by an API key.

Base URL

https://emails.aiosis.com/api/v1

Authentication

Every request carries a bearer key. Create one in the app under Settings → API keys; it is shown once and stored only as a SHA-256 hash, so it cannot be recovered — create a new one instead.

Authorization: Bearer sk_live_xxxxxx_…

A key belongs to exactly one account and carries a subset of these scopes. A call outside its scopes is refused with 403, never silently narrowed.

contacts:readcontacts:writecampaigns:readcampaigns:writemessages:sendstats:readmessages:readtemplates:readtemplates:writeevents:writedomains:readwebhooks:managemail:readmail:send

Send an email

The transactional endpoint. Needs the messages:send scope.

curl -X POST https://emails.aiosis.com/api/v1/messages \
  -H "Authorization: Bearer $AIOSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "to": "customer@example.com",
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "text": "Thanks for your order.",
        "fromEmail": "billing@yourdomain.com",
        "fromName": "Acme Billing",
        "replyTo": "support@yourdomain.com",
        "tags": ["receipt"]
      }'

Tracking

Every message the API accepts gets a record you can read back, and opens and clicks are tracked first-party — a pixel and rewritten links on this domain, not a third party's.

  • GET /api/v1/events — delivery, open, click, bounce and complaint events.
  • GET /api/v1/campaigns/{id}/stats — per-campaign aggregates.
  • GET /api/v1/suppressions — who must not be mailed, and why.
  • Outbound webhooks push the same events to your endpoint, signed — see below.

The same data drives the dashboard in the app, so what you read over the API is what the interface shows.

Webhooks

Register an endpoint with POST /api/v1/webhooks. Deliveries are signed so you can verify they came from us:

X-Aiosis-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<unix>.<raw body>">
X-Aiosis-Event: contact.subscribed
X-Aiosis-Delivery: whk_…

Compute the HMAC over <timestamp>.<raw body> with the endpoint secret and compare in constant time. Reject anything older than five minutes. Delivery is at-least-once, so deduplicate on the payload id. A failing endpoint is retried with exponential backoff for 24 hours, then dead-lettered and replayable.

Pagination, limits and errors

Pagination

Collections are cursor-paged. Follow nextCursor until it is null; a short page means the end.

Rate limit

600 requests per minute per key, so one integration cannot starve another. Every response carries X-RateLimit-Remaining.

Errors

JSON with a message. An object belonging to another account is 404, not 403, so ids stay unenumerable.

Endpoint reference

42 endpoints

Generated from the same definition that serves the OpenAPI document, so it cannot drift from the running API.

contacts

GET/api/v1/contactsList contactscontacts:read
POST/api/v1/contactsCreate or update a contactcontacts:write
GET/api/v1/contacts/{id}Fetch one contactcontacts:read
PATCH/api/v1/contacts/{id}Update a contactcontacts:write
DELETE/api/v1/contacts/{id}Erase a contact (GDPR)contacts:write
POST/api/v1/contacts/{id}/unsubscribeUnsubscribe a contactcontacts:write
GET/api/v1/contacts/{id}/subscriptionsA contact's subscription to every categorycontacts:read
PUT/api/v1/contacts/{id}/subscriptionsRecord subscription choices made in your own UIcontacts:write

lists

GET/api/v1/listsList mailing listscontacts:read
POST/api/v1/listsCreate a mailing listcontacts:write
GET/api/v1/lists/{id}/contactsList the subscribed contacts of a listcontacts:read

campaigns

GET/api/v1/campaignsList campaignscampaigns:read
POST/api/v1/campaignsCreate a campaigncampaigns:write
GET/api/v1/campaigns/{id}Fetch one campaigncampaigns:read
POST/api/v1/campaigns/{id}/sendSend a campaign nowcampaigns:write
POST/api/v1/campaigns/{id}/scheduleSchedule a campaigncampaigns:write
POST/api/v1/campaigns/{id}/pausePause a sending campaigncampaigns:write
POST/api/v1/campaigns/{id}/cancelCancel a campaigncampaigns:write
GET/api/v1/campaigns/{id}/statsCampaign performancestats:read

messages

POST/api/v1/messagesSend an emailmessages:send
POST/api/v1/messages/batchSend one template to many recipientsmessages:send
GET/api/v1/messages/{id}Fetch one message, its events and its failure reasonmessages:read

templates

GET/api/v1/templatesList templates, every localetemplates:read
POST/api/v1/templatesCreate a template, or a new locale of a keytemplates:write
GET/api/v1/templates/{key}Every locale of one template keytemplates:read
PATCH/api/v1/templates/{key}Edit one locale of a templatetemplates:write
DELETE/api/v1/templates/{key}Delete a template (one locale, or all)templates:write
POST/api/v1/templates/{key}/publishPublish the current drafttemplates:write
POST/api/v1/templates/{key}/previewRender a template without sendingtemplates:read
POST/api/v1/templates/{key}/testSend the draft to one addresstemplates:write

categories

GET/api/v1/categoriesEmail categories a recipient can opt into or out ofcontacts:read

suppressions

GET/api/v1/suppressionsList suppressionscontacts:read
POST/api/v1/suppressionsSuppress an addresscontacts:write

imports

POST/api/v1/importsImport contacts from CSVcontacts:write

webhooks

GET/api/v1/webhooksList webhook endpointscampaigns:read
POST/api/v1/webhooksRegister a webhook endpointcampaigns:write
PATCH/api/v1/webhooks/{id}Update a webhook endpointcampaigns:write
DELETE/api/v1/webhooks/{id}Delete a webhook endpointcampaigns:write
POST/api/v1/webhooks/{id}/rotateRotate an endpoint signing secretcampaigns:write
GET/api/v1/webhooks/deliveriesList dead-lettered deliveriescampaigns:read
POST/api/v1/webhooks/deliveries/{id}/replayReplay a dead-lettered deliverycampaigns:write

events

POST/api/v1/eventsRecord a custom eventcontacts:write

Running the platform? The console is at/admin.