Skip to navigation

Email Service

Email Service is a sending service that lets your application send transactional email, such as order confirmations, password resets and alerts, from a domain you own, like acme.com. Your application sends each message with one HTTPS request (or over SMTP), and the portal shows what happened to it: delivered, bounced, or marked as spam.

Email Service is turned on per organization. If Email Service isn’t under Tools in your sidebar, contact support to request access.

When to use it

You need to…UseNotes
Send email from your own app or website codeHTTPS API (POST /v1/emails)Fastest to set up from code; returns an ID you can track
Send from software that only speaks SMTP (a CMS, an identity provider, a mail library)SMTP relaySame domains, senders, limits and logs as the API
Receive email, or give people mailboxesNot Email ServiceEmail Service only sends. A sender address is not an inbox.
Manage domains, senders and keys from codeThe portalDomains, senders, keys, suppressions and webhooks have no public API

Email Service is built for transactional email: messages a person expects because of something they did. Send only to people who asked for your email.

How it works

  1. Choose a plan for the workspace. Until a plan is active, Email Service shows only the plan page.
  2. Add your domain and publish the DNS records the portal shows at your DNS provider. IBEE checks them and marks the domain Active.
  3. Register senders: the exact From addresses you will use, such as orders@acme.com.
  4. Create an API key and send. Delivery results appear under Emails and, optionally, at your webhook.

Before you begin

  • Role: an organization Owner or Admin to choose the plan and create API keys; anyone with write access to the workspace (Owner, Admin, Technical) to add domains and senders. See Team members & access roles.
  • Identity verification of your own account, for every change. See Verify your identity.
  • Access to your domain’s DNS settings at your DNS provider (for example Cloudflare, GoDaddy or Route 53).
  • Funds for the plan. Plans have a monthly price and are billed to your organization.

To open Email Service, open a workspace and click Email Service under Tools. Once a plan is active, the page has eight tabs: Overview, Emails, Metrics, Domains, Logs, API keys, Webhooks and Settings.

Choose a plan

1

Open the plan page

Open Email Service. Until the workspace has a plan, this is the only page.

2

Pick a plan

Under Choose plan, the table lists each plan’s Emails per month, Domains and Price. Every plan includes API and SMTP sending, webhooks, delivery logs and metrics, bounce and complaint suppression, and DKIM signing on your domain. For more than the largest plan, use Talk to Sales.

3

Activate it

Click Activate plan. When the plan is active, the eight tabs appear.

Recipients beyond your plan’s monthly allowance are billed separately. Settings shows your Plan allowance, Domain limit, and this month’s Used, Included this month and Remaining, with Upgrade plan.

Add and verify your domain

1

Add the domain

In Overview or Domains, click Add domain. Under Sending root domain, enter a domain you control, such as acme.com, without @ or https://. Click Continue to DNS authentication.

2

Wait for the records

The domain opens on its own page with four steps: Choose domain, Add DNS records, Verify connection and Register sender. The Add DNS records step fills in by itself once IBEE has prepared the records.

3

Add the records at your DNS provider

Add each record exactly as shown. The table gives each record’s Purpose, Type, Name, Value and Priority, with copy buttons. Copy setup instructions copies them all and Download DNS records saves them to a file. Click I’ve added the DNS records when you’re done.

4

Verify the connection

Click Verify connection. The page updates by itself while IBEE checks.

Don’t change your domain’s nameservers or delete its website or mailbox records. Only add the records shown.

What the records do, in plain terms:

RecordUsuallyWhat it proves
DKIM (DomainKeys Identified Mail)A TXT record on <selector>._domainkey.acme.com, or CNAME records on <token>._domainkey.acme.comMail from IBEE really is signed for your domain
Return-PathA CNAME record on send.acme.comBounces come back to IBEE, so bounced addresses are suppressed
DMARC (Domain-based Message Authentication, Reporting and Conformance)A TXT record on _dmarc.acme.com with v=DMARC1; p=none;Tells receiving servers what to do with mail that fails the checks. IBEE doesn’t wait for it before activating the domain.

Tips for the DNS provider:

  • Names are relative to your domain. If your provider adds acme.com to the name by itself, don’t type it twice.
  • Leave the TTL (how long other servers may cache the record) at your provider’s default.
  • On Cloudflare, set each CNAME to DNS only (grey cloud). Proxied records can’t be verified.

How long it takes: new records can take from a few minutes to many hours to be visible. IBEE re-checks by itself every minute for the first 12 minutes, then every 10 minutes, then every hour, for about 72 hours in total. After that, click Verify connection again.

Domain status

StatusWhat it meansWhat to do
Setting upIBEE is preparing the domainWait
Needs DNS setupA delegated subdomain is waiting for its NS (nameserver) recordsAdd the NS records at your DNS provider
Checking nameserversIBEE is checking that delegationWait
Configuring emailIBEE is setting up email authenticationWait
Verification pendingIBEE is waiting to see your DNS recordsCheck the records, then wait or click Verify connection
ActiveVerified: you can register senders and create API keysContinue
RetryingA check failedFix the records the page points to, then click Retry setup
SuspendedSending from this domain is stoppedContact support
CancelledSetup was cancelledAdd the domain again if you still need it
RemovingThe domain is being removedWait

To remove a domain: open it, go to Settings and click Remove domain (or use the remove icon in Domains), type the domain name, and confirm. Afterwards, delete its records at your DNS provider.

Register senders

A sender is an exact From address your application may use. The API rejects any From address that isn’t a registered sender on an Active domain.

1

Open the domain’s senders

Open an Active domain and go to the Register sender step or the Senders tab.

2

Add the sender

Click Add sender. Enter the Sender name: only the part before @, such as orders (1–64 lowercase letters, digits, ., _, + or -). Optionally add a Display name such as Acme Orders and a Reply-To address.

The saved Display name and Reply-To are used by Send test email in the portal. The API doesn’t apply them: send fromName and replyTo with each request.

To stop using a sender, click its remove icon and confirm Remove sender. The row stays as Disabled; Re-enable brings it back.

Create an API key

An Email Service API key lets your application send. It works only in its workspace and only for the domains you pick. Platform API tokens can’t send email, and an Email API key can’t manage anything else.

1

Open API keys

In Email Service, open API keys and click Create API key.

2

Fill in the key

  • Name: for example production-app (up to 80 characters).
  • Permission: Sending access (send), Sending + read (send, and read a message’s status), or Read only (read status, can’t send).
  • Domains: one or more Active domains in this workspace, up to 50. Select all picks every one.
  • Expires: Never (default), 30 days, 90 days or 1 year.

Click Create API key.

3

Save the key

The Save your API key dialog shows the key once. Click Copy API key, store it on your application server (never in browser code), tick I saved the key in a safe place, and click Done.

The organization API Tokens page also has an Email Tokens tab. Create Email Token makes a send-only key for one domain, with Token expiration of No expiration, 7 days, 30 days, 90 days (default) or 1 year. See API Tokens.

To revoke a key: click Revoke on its row and confirm Revoke key. Requests with it fail at once; messages already accepted still go out. Turn on Show revoked and expired to see inactive keys.

Send an email

Send a POST request to the send endpoint. The Send your first email step on Overview shows ready-made cURL, Node.js and Python samples with the address for your account:

POST https://ibee-email-send-api-prod.bifrosts.workers.dev/v1/emails

Headers

HeaderRequiredValue
AuthorizationYesBearer <api-key>
Content-TypeYesapplication/json
Idempotency-KeyNo, but recommendedA unique ID for this message, 8–256 characters of letters, digits, ., _, : and -. Makes retries safe (see below).

Body

FieldRequiredDescription
fromYesA registered sender, such as orders@acme.com, or "Acme Orders <orders@acme.com>"
toYesOne address, or a list of up to 50
subjectYes1–200 characters
textOne of text or htmlPlain-text body, up to 100,000 characters
htmlOne of text or htmlHTML body, up to 250,000 characters
fromNameNoDisplay name for the From address (longer than 120 characters is cut)
replyToNoOne address or a list
cc, bccNoOne address or a list. to, cc and bcc together: at most 50 unique addresses
attachmentsNoUp to 20 items of {"filename": "...", "content": "<base64>"}, 40 MB in total
headersNoUp to 50 extra headers, as {"Name": "value"}
tagsNoUp to 50 items of {"name": "...", "value": "..."}
scheduledAtNoAn ISO 8601 time in the future, up to 30 days ahead

Examples

curl https://ibee-email-send-api-prod.bifrosts.workers.dev/v1/emails \
-H "Authorization: Bearer $IBEE_EMAIL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-confirmation" \
-d '{
"from": "orders@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>"
}'

Verify it worked

A successful request returns 202 Accepted: the message is queued, not yet delivered.

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

Open Emails and find the message by its id. Its status moves from Accepted to Delivered (or Bounced). With a Sending + read or Read only key, GET /v1/emails/{id} returns the same status.

Retries and the Idempotency-Key

If a request times out or the network fails, send it again with the same Idempotency-Key. When the key was already used in the workspace, the API returns the first message’s id with "duplicate": true and doesn’t send a second copy. Without the header, IBEE makes a new key for every request, so a retry can send the message twice.

Build the key from your own records, such as order-1042-confirmation, and use a new one for every distinct email.

Send several emails at once

POST /v1/emails/batch takes a JSON array of 1–100 message objects, each shaped like the body above, and returns 202 with {"data": [{"id", "status", "duplicate"}, …]}. Give each item its own idempotency_key. If one item is invalid, the request stops there and returns that item’s error; items before it are already accepted.

Send over SMTP

Use these settings in software that sends mail over SMTP (also shown under Settings → SMTP):

SettingValue
Hostsmtp.ibee.email
Port465
EncryptionSSL/TLS (implicit TLS, not STARTTLS)
Usernameibee
PasswordAn Email Service API key with Sending access

The From address must be a registered sender on an Active domain. SMTP messages count toward the same limits and appear in Emails like API messages.

Track delivery

Emails lists every message from the workspace with To, Status, Subject, From and Sent. It shows the last 15 days by default; filter by text, Status, Domain and time. Click a message for its delivery timeline and content.

StatusMeaning
AcceptedThe API accepted the message
QueuedWaiting to be sent
SubmittedHanded to the recipient’s mail server
DeferredTemporarily refused; IBEE is retrying
DeliveredThe recipient’s mail server accepted it
BouncedPermanently rejected. The address is added to the suppression list.
RejectedRejected; it won’t be delivered
FailedCouldn’t be sent
ComplaintThe recipient marked it as spam. The address is added to the suppression list.

Logs lists API requests made with the workspace’s keys (Endpoint, Status, API key, Duration, User agent, Created); request bodies aren’t stored. Metrics shows sent, delivered, bounce and complaint figures for the last 24 hours, 7, 30 or 90 days.

To check your setup without code, click Send test email in Overview or Emails. Test emails are real messages and count toward your limit.

Suppressions

The suppression list holds addresses the workspace won’t send to. Open Emails and switch to Suppressions. Bounced and complaining addresses are added automatically; Add address adds one by hand. Remove from list takes an address off, but sending again to an address that bounced or complained can hurt your sender reputation. If it bounces or complains again, it is added back.

Webhooks

A webhook sends each delivery event to an HTTPS address in your application, so you don’t have to poll.

1

Add an endpoint

In Webhooks, click Add endpoint. Enter a public https:// Endpoint URL, such as https://api.acme.com/webhooks/email, and choose the Events. Click Add endpoint.

2

Save the signing secret

The Save your signing secret dialog shows it once. Store it on your server, tick I’ve saved the secret, and click Done.

EventSent when
email.deliveredThe recipient’s server accepted the message
email.deferredDelivery was delayed and is being retried
email.bouncedThe message bounced permanently
email.rejectedThe message was rejected
email.failedThe message couldn’t be sent
email.complainedThe recipient reported it as spam

Each delivery is a POST with a JSON body such as:

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

Delivery rules: answer with any 2xx status within 15 seconds. Redirects aren’t followed. Timeouts, network errors and 408, 425, 429 or 5xx answers are retried, up to 7 attempts, with the wait doubling from 5 seconds. The same event can arrive twice: skip events whose x-ibee-event-id you have already handled. Events that happen while an endpoint is disabled are never sent.

Check the signature before trusting a delivery. Each request has x-ibee-signature (v1= plus a hex HMAC-SHA256 signature, a fingerprint made with your signing secret), x-ibee-timestamp (Unix seconds) and x-ibee-event-id. Compute HMAC-SHA256 of timestamp + "." + rawBody with your secret, compare it with the value after v1= in constant time, and reject timestamps more than 5 minutes old.

import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["IBEE_WEBHOOK_SECRET"].encode()
@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)) > 300:
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()
print(event["type"], event["data"].get("messageId"))
return "", 204

Open an endpoint to Edit it, Send test event, Disable or Enable it, or Rotate secret (the old secret stops working at once). Deliveries shows each attempt and its last error.

Limits

Value
Daily limitSet by your plan. It counts recipients (every to, cc and bcc address), and resets at 00:00 UTC. Overview → Emails today shows today’s count and limit.
Monthly allowance and domainsSet by your plan; see Settings
Recipients per message50 (to + cc + bcc)
Messages per batch request1–100
Subject1–200 characters
text / html body100,000 / 250,000 characters
Attachments20 per message, 40 MB in total (base64)
Request body42 MB
Idempotency-Key8–256 characters
Custom headers, tags50 each
SchedulingUp to 30 days ahead
Domains per API key1–50 (an Email Token: 1)
API key name80 characters
Webhook answer time15 seconds; up to 7 attempts
Reputation targetsBounce rate below 2%, complaint rate below 0.05% (shown on Overview)

A message repeated with an already-used Idempotency-Key doesn’t count toward the daily limit.

Troubleshooting

Errors return JSON such as {"error": {"code": "recipient_suppressed", "message": "…"}}. Every response has an x-request-id header; include it when you contact support.

You seeWhat it meansWhat to do
Email Service shows only a plan pageThe workspace has no active planChoose a plan and click Activate plan
Domain stuck on Verification pendingThe records aren’t visible yet, or don’t matchCompare each record with the portal, check the name isn’t doubled (send.acme.com.acme.com), turn off the Cloudflare proxy, then Verify connection
401 api_key_requiredNo Authorization: Bearer headerAdd the header
401 api_key_invalidThe key is wrong, revoked or expiredCreate a new key
403 sender_not_allowedThe From address isn’t a registered sender on an Active domainRegister the sender
403 sender_not_allowed_by_keyThe key doesn’t include the sender’s domainCreate a key for that domain
403 scope_missingThe key is Read onlyUse a key with Sending access
403 plan_payment_due, plan_suspended or plan_cancelledThe workspace’s email plan is unpaid, suspended or endedSettle the payment, or choose a plan, in the portal
403 tenant_inactiveEmail Service isn’t active for this workspaceContact support
400 recipient_invalid, sender_invalid or reply_to_invalidAn address is malformed, or to is empty or has more than 50Fix the address list
400 recipient_limit_exceeded or recipient_duplicateMore than 50 recipients in total, or an address appears twiceSplit the message, or remove duplicates
400 subject_invalid or body_emptyThe subject is empty or too long, or there is no text or htmlFix the subject or add a body
400 idempotency_key_invalidThe key isn’t 8–256 allowed charactersUse letters, digits, ., _, : and -
400 attachments_invalid or 413 attachments_too_largeAn attachment has no filename or base64 content, there are more than 20, or they exceed 40 MBFix or shrink the attachments
409 recipient_suppressedThe address is on the suppression listRemove it from Suppressions only if you’re sure it’s valid
409 domain_limit_reached (when adding a domain)Your plan’s domain limit is usedUpgrade plan
413 body_too_large or request_too_largeThe body or the whole request is too largeShorten the content
415 content_type_invalidContent-Type isn’t application/jsonSet the header
429 daily_limit_reachedToday’s limit is used (details has limit, used and requested)Wait until 00:00 UTC, or upgrade your plan
429 quota_or_acceptance_conflict or 500 internal_errorA temporary problemRetry with the same Idempotency-Key