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
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
- Choose a plan for the workspace. Until a plan is active, Email Service shows only the plan page.
- Add your domain and publish the DNS records the portal shows at your DNS provider. IBEE checks them and marks the domain Active.
- Register senders: the exact From addresses you will use, such as
orders@acme.com. - 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
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
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.
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.
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:
Tips for the DNS provider:
- Names are relative to your domain. If your provider adds
acme.comto 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
CNAMEto 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
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.
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.
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.
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:
Headers
Body
Examples
Verify it worked
A successful request returns 202 Accepted: the message is queued, not yet delivered.
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):
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.
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.
Each delivery is a POST with a JSON body such as:
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.
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
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.
Related pages
- API Tokens: the Email Tokens tab and other credentials
- Verify your identity: needed before any change
- Billing and usage: how plans are billed
- Contact support: request access or help with a domain
