Email Service

Email Service sends transactional email, such as order confirmations, password resets, and notifications, from a subdomain you own, like email.acme.com. Your application sends each message with one HTTPS request, and the portal shows its delivery status.

• Your domain, managed authentication. You delegate one unused subdomain to IBEE with two NS records. IBEE then creates and maintains the SPF, DKIM, DMARC, and return-path (bounce) records inside that subdomain.
• HTTPS API only. Messages are sent with POST /v1/emails. SMTP relay is not available.
• Send-only. Sender addresses are identities for outgoing mail, not mailboxes. Email Service does not receive email.

Domains, senders, suppressions, and webhooks are managed in the portal. They have no public API yet.

Before you begin

• An organization and a workspace. Email Service resources belong to a workspace.
• Access to the DNS settings of your company domain, such as acme.com, at your DNS provider.
• An unused subdomain to send from, such as email, notify, or updates. It must not already serve a website or a mailbox.
• To create Email Tokens: an organization admin whose account is verified (Verify your identity).

How it works

To open Email Service, select your organization and workspace, then click Email Service under Tools in the sidebar. The page has four tabs: Overview, Domains, Activity, and Settings. The Overview tab shows a three-step checklist (Add a sending domain, Create a token, Send a test email) and cards for Emails today, Delivery rate, Bounce rate, and Active domains.

Add a sending domain

If the sending domain already exists in the workspace, the dialog links to it so you can continue its setup.

The Domains tab lists every sending domain with its Status, Next action, and creation date. You can search by name and filter by All domains, Verified domains, or Needs setup or attention. Click Continue setup or Manage to open a domain.

Add NS records and verify

To see the authentication records IBEE manages, expand What does IBEE configure? in the Verify connection step. It lists the SPF, DKIM, DMARC, and bounce records inside the delegated subdomain. They are for reference only. Do not copy them into your company domain’s DNS.

Domain status

Each NS record also has its own status: Pending, Checking, Verified, Missing, or Incorrect. Missing or Incorrect means the record at your DNS provider doesn’t match the value shown.

Remove a domain

Open the domain and click Remove, then type the domain name to confirm. New sends from the domain stop before its resources are released, and the domain shows Removing. Afterwards, delete the subdomain’s NS records at your DNS provider.

Register senders

A sender is the exact From address your application is allowed to use. Registering a sender does not create an inbox. The API rejects any From address that is not a registered sender on an active domain.

The domain’s sender table shows each Address, Display name, Reply-To, and Status. To set the display name and Reply-To on a message sent through the API, include fromName and replyTo in the request (see Send an email).

To remove a sender, click the delete icon on its row. Applications can no longer send from that address.

Create an Email Token

Applications authenticate to the send API with an Email Token. Each token can only send email from one verified sending domain. It cannot manage infrastructure or change Email Service settings. Platform API tokens cannot send email.

Only organization admins can create or revoke Email Tokens, and their account must be verified.

To revoke a token, click Revoke on its row. Applications using it stop sending immediately. Messages that were already accepted are not cancelled.

For platform API tokens and other credential types, see API Tokens.

Send an email

Send one message per request:

POST https://api.ibee.email/v1/emails

Headers

Body

Each request has exactly one recipient. To email several people, send one request per recipient, each with its own Idempotency-Key. Attachments, CC, and BCC are not supported.

Examples

curl https://api.ibee.email/v1/emails \
  -H "Authorization: Bearer $IBEE_EMAIL_TOKEN" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "orders@email.acme.com",
    "fromName": "Acme Orders",
    "to": "buyer@example.com",
    "replyTo": "support@acme.com",
    "subject": "Your order is confirmed",
    "text": "Thank you for your order.",
    "html": "<p>Thank you for your order.</p>"
  }'

Response

A successful request returns 202 Accepted. This means the message was accepted and queued. Delivery happens afterwards and is reported in Activity and through webhooks.

{
  "id": "msg_Xk3v9Qp2LmN7tRzA",
  "status": "accepted",
  "duplicate": false
}

Idempotency

The Idempotency-Key makes retries safe. If a request fails because of a timeout or network error, retry it with the same key. When a key has already been used in the workspace, the API returns the original message’s id with "duplicate": true and does not send it again.

Derive the key from your own record, such as order-1042-confirmation. Use a new key for every distinct email. A reused key never sends a second message, even if the body changed.

Errors

Errors return a JSON body with a machine-readable code:

{
  "error": {
    "code": "recipient_suppressed",
    "message": "Recipient is on this workspace's suppression list."
  }
}

Every response includes an x-request-id header. Include it when you contact support.

Send a test from the portal

To check your setup without writing code, click Send test in the Overview checklist or Send test email on the Activity tab. Choose a registered sender under From, enter the To, Subject, and Message, then click Send. The result appears in Activity. Test emails are real messages and count toward the daily limit.

Activity and message timeline

The Activity tab lists recent messages with From, To, Subject, Status, and Created. Click Refresh to load new results, and Load older messages to page back. The search box filters the messages already loaded on the page by ID, address, subject, or status.

Click a message’s subject to open its details. They show the message ID, From, To, and Subject, plus a timeline of every delivery event with its time, a description, and the SMTP status code when the recipient’s mail server returned one.

Suppressions

The suppression list holds recipients this workspace will not send to. A request to a suppressed recipient fails with 409 recipient_suppressed.

To open it, click Suppressed recipients on the Activity tab. Each entry shows the Recipient, Reason, and the date it was Added.

To block an address yourself, click Add suppression, enter the email address, and confirm. If an automatic suppression was added in error, contact support.

Webhooks

Webhooks send signed delivery events to an HTTPS endpoint in your application. They are optional. You host the receiver.

To add an endpoint:

New endpoints receive all six event types. To manage an existing endpoint, choose it from Webhook endpoint. Its status is Active, Disabled, or Failing, and the panel shows the latest delivery result.

• Update webhook: change the endpoint URL. Subscriptions and status are kept.
• Disable webhook or Enable webhook: stop or resume deliveries to the endpoint.
• Rotate secret: issue a new signing secret. The old secret stops working immediately, so update your receiver right away.

Events

Each delivery is a POST with a JSON body:

{
  "id": "evt_4fT8wQm1ZkP0sVnB",
  "type": "email.bounced",
  "createdAt": "2026-10-01T09:30:12.000Z",
  "data": {
    "messageId": "msg_Xk3v9Qp2LmN7tRzA",
    "from": "orders@email.acme.com",
    "to": "buyer@example.com",
    "subject": "Your order is confirmed",
    "status": "bounced",
    "smtpStatusCode": "550",
    "smtpResponse": "5.1.1 User unknown"
  }
}

data.messageId matches the id returned by POST /v1/emails. Payloads can include more fields. Ignore any you don’t use.

Delivery and retries

• Return any 2xx status within 15 seconds to acknowledge an event.
• Redirects are not followed.
• Timeouts, network errors, and 408, 425, 429, and 5xx responses are retried with increasing delays. Other responses are not retried.
• Retries can deliver the same event more than once. Deduplicate with the x-ibee-event-id header.

Verify signatures

Every delivery includes three headers:

To verify a delivery:

1. Compute HMAC-SHA256 with your signing secret over the exact string timestamp + "." + rawRequestBody. Use the raw bytes you received, not re-serialized JSON.
2. Compare the hex digest with the value after v1= using a constant-time comparison.
3. Reject timestamps more than 5 minutes from your server’s clock.

import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["IBEE_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 300
@app.post("/webhooks/email")
def ibee_email_webhook():
    raw_body = request.get_data()
    timestamp = request.headers.get("x-ibee-timestamp", "")
    signature = request.headers.get("x-ibee-signature", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        abort(400)
    expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    if not signature.startswith("v1=") or not hmac.compare_digest(signature[3:], expected):
        abort(400)
    event = request.get_json()
    # Skip events whose x-ibee-event-id you have already processed.
    print(event["type"], event["data"].get("messageId"))
    return "", 204

Keep the signing secret on your server. Never put it in frontend code.

Limits and sandbox

Workspaces start with sandbox access. A domain that shows Sandbox ready is verified for sandbox sending, and sandbox recipient and quota restrictions apply. To ask about production access or a higher limit, contact support.

Each workspace has a daily sending limit. The Emails today card on the Overview tab shows how many messages you have sent today and your daily limit. When the limit is reached, the API returns 429 daily_limit_reached until the next day starts (00:00 UTC). Test emails sent from the portal count toward the limit. Repeated requests with an already-used Idempotency-Key do not.

Keep your bounce rate low. The Bounce rate card on Overview targets below 2%. Send only to addresses that asked for your email, and respect the suppression list.

Related

• API Tokens: platform API tokens and the other credential types managed on the same page.
• Verify your identity: required before creating Email Tokens.
• Contact support: request Email Service access, production access, or help with a domain.