Docs

Rykon Mail Docs

Build email into your product

One REST API for transactional email, your audience, campaigns, domains, mailboxes and AI agent inboxes. JSON in, JSON out, a scoped key per integration, and an error that says what to change.

Quickstart API reference

What you can build

Transactional emailReceipts, sign-in links and alerts from your own domain, with idempotency and limits of their own.Read the guide Audience syncAdd the people who sign up in your app to your audience, with the consent they gave and the topics they chose.Read the guide Campaigns from your backendCreate, test, schedule and measure campaigns from the systems that already know your customers.Read the guide Agent mailboxesGive an AI agent an address of its own, reached over REST or the MCP server, held to rules you set.Read the guide

Quickstart

From no key to a sent email and a new contact, in about five minutes.

  1. Create an API key

    In the console, open Developers and make a key. Only an owner or an admin can. Give it just the scopes this integration needs: mail:send to send, audience:write to add contacts.

    The key is shown once. Put it in your server's environment; if it is ever lost, revoke it and make another.

    Terminal
    # Keep it in your server's environment, never in a browser or a repository
export RYKON_MAIL_KEY="rmk_live_..."

  2. Send an email

    Send from an address on one of your domains once it is set up for sending. The category says what kind of message it is, and an idempotencyKey makes a retry safe: the same key returns the first result instead of sending twice.

    More in Sending email.

    POST/emails
    curl -X POST https://app.rykonmail.com/api/v1/emails \
  -H "Authorization: Bearer $RYKON_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "orders@northwind-local.test",
    "fromName": "Northwind Traders",
    "to": "jamie.chen@example.com",
    "replyTo": "help@northwind-local.test",
    "subject": "Your receipt for order 10482",
    "text": "Thanks for your order.\n\nOrder 10482: 2 x Linen apron, $48.00.\nTotal paid: $48.00.",
    "html": "<p>Thanks for your order.</p><p>Order 10482: 2 x Linen apron, $48.00.<br>Total paid: <strong>$48.00</strong>.</p>",
    "category": "receipt",
    "idempotencyKey": "order-10482-receipt"
  }'
    Response
    200 OK
    {
  "id": "682e5ffd-1528-4b9e-9b81-65903d3d9593",
  "category": "receipt",
  "from": "orders@northwind-local.test",
  "to": "jamie.chen@example.com",
  "subject": "Your receipt for order 10482",
  "state": "sent",
  "messageId": "simulated-fa61a1bd-2389-4b00-ab0c-63ac54867b0c",
  "error": null,
  "createdAt": "2026-10-30T06:18:05.177Z"
}

  3. Add a contact

    When someone signs up in your app, add them to your audience with the consent they gave. Campaigns and automations reach them from there, and their own choices (topics, unsubscribing) are kept for you.

    More in Contacts and consent.

    POST/contacts
    curl -X POST https://app.rykonmail.com/api/v1/contacts \
  -H "Authorization: Bearer $RYKON_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie.chen@example.com",
    "name": "Jamie Chen",
    "tags": [
      "customer",
      "newsletter"
    ],
    "attributes": {
      "plan": "pro",
      "city": "Austin"
    },
    "consent": {
      "text": "Yes, send me product news and offers. I can unsubscribe at any time.",
      "source": "Checkout opt-in",
      "ip": "203.0.113.24"
    }
  }'
    Response
    201 Created
    {
  "id": "00410db1-2799-4dd4-afef-11f95befa5af",
  "email": "jamie.chen@example.com",
  "name": "Jamie Chen",
  "status": "subscribed",
  "tags": [
    "customer",
    "newsletter"
  ],
  "attributes": {
    "city": "Austin",
    "plan": "pro"
  },
  "consent_source": "api:Checkout opt-in",
  "consent_at": "2026-10-30T06:13:46.762Z",
  "confirmed_at": "2026-10-30T06:13:46.762Z",
  "unsubscribed_at": null,
  "created_at": "2026-10-30T06:13:46.762Z",
  "created": true
}

The reference

72 endpoints in 10 groups, also as OpenAPI 3.1.

Emails2Send transactional email from your application: receipts, password resets, alerts.Contacts12The people in your audience, with their consent and the topics they chose.Topics4What people can subscribe to, so each one hears only about what they asked for.Forms5Sign-up forms and where they are live.Campaigns19Create, test, schedule and measure campaigns.Automations8Journeys that run when someone subscribes.Domains6Your sending domains and the DNS records that prove them.Mailboxes4Mailboxes on your domains.Aliases4Extra addresses that deliver to a mailbox.AI agents8Agents with mailboxes of their own, and the messages waiting for your approval.