Email API

Send transactional email from your own verified domain.

Email on MsGine is for transactional messages only: receipts, verification codes, password resets, order and delivery updates, appointment reminders, security alerts and service notices (for example planned maintenance or a change to your terms). Marketing email (promotions, offers, newsletters) is not available yet. See the Acceptable Use Policy.

Before you send

1. Add your sending domain in the dashboard under Settings → Email. MsGine shows two DNS records to publish at your DNS provider:

   Type	Purpose
   TXT	DKIM: proves the email was sent by you
   CNAME	Bounce address: lets MsGine receive bounces for your domain

   Click Check verification once they are published. DNS changes can take up to 48 hours. If your DNS is on Cloudflare, set the CNAME to DNS only (grey cloud): a proxied record hides the CNAME and cannot be verified. Your first domain is free; each additional domain costs UGX 5,000.

   Until your domain is verified you can send from the shared domain mail.msgine.net, with a daily limit.

2. Buy an email bundle under Billing. Every email is paid from your bundles, one email per recipient. Bundles are valid for 12 months; see pricing.

3. Create an API key with the SEND_EMAIL scope (or FULL_ACCESS).

Send email

Endpoint

POST https://api.msgine.net/api/v1/developers/email

Request

curl -X POST https://api.msgine.net/api/v1/developers/email \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageType": "transactional",
    "from": "Acme Receipts <receipts@acme.co.ug>",
    "to": "amina@example.com",
    "subject": "Your receipt for order 1042",
    "text": "Thank you for your order. Total paid: UGX 85,000.",
    "html": "<p>Thank you for your order.</p><p>Total paid: <b>UGX 85,000</b>.</p>",
    "idempotencyKey": "receipt-1042"
  }'

Parameters

Parameter	Type	Required	Description
messageType	string	Yes	transactional. marketing is refused until marketing email is available
from	string	Yes	address@domain or Name <address@domain>. The domain must be one of your verified domains, or mail.msgine.net
to	string	Yes	Recipient address, or several separated by commas
cc	string	No	Addresses separated by commas
bcc	string	No	Addresses separated by commas
subject	string	Yes	Subject line
text	string	One of text, html	Plain-text body
html	string	One of text, html	HTML body
scheduledFor	string	No	ISO 8601 time to send at
idempotencyKey	string	No	Max 64 characters. A retried request with the same key returns the first response and sends nothing again

Recipients. One email can have at most 10 recipients across to, cc and bcc. To send the same notice to many people, send one request per recipient (or use a workflow or a campaign with message type transactional), so each person gets their own email and nobody sees anyone else's address.

Choosing the domain. If you have several verified domains, the domain in from decides which one is used: receipts@acme.co.ug sends from acme.co.ug, alerts@notify.acme.co.ug from notify.acme.co.ug. There is no separate field.

Suppressed addresses. Addresses that hard-bounced, marked your email as spam, unsubscribed, or are on your opt-out list are removed before sending and are not charged. If every recipient is removed, the request fails with 400.

Response

{
  "id": "6f1c2a90-3b1e-4d0b-9c41-2a7e5d8b0f13",
  "channel": "email",
  "from": "Acme Receipts <receipts@acme.co.ug>",
  "to": ["amina@example.com"],
  "subject": "Your receipt for order 1042",
  "status": "pending",
  "cost": 0,
  "currency": "UGX",
  "sandbox": false
}

The email is queued and sent within seconds. cost is 0 because email is paid from your bundles, not your balance. With a sandbox API key the request is validated and recorded but nothing is sent and no bundle email is used.

Errors

Status	Meaning
400	Invalid request; messageType missing or marketing; more than 10 recipients; all recipients suppressed; not enough email credits (Not enough email credits. Buy an email bundle to send this email.)
401	Missing or invalid API key
403	The key lacks the SEND_EMAIL scope, the from domain is not one of your verified domains, or email sending is suspended for this key because of a high bounce or complaint rate
429	Rate limit exceeded

Email history

GET https://api.msgine.net/api/v1/developers/email/history?page=1&limit=20

Returns your sent emails, newest first, with each email's status: pending, sent, delivered, bounced or failed.

Webhook events

Subscribe a webhook to:

Event	When
email.sent	The email was handed to the mail provider
email.failed	The email could not be sent. Its emails are returned to your bundle

Bounces and complaints

When a recipient's mailbox does not exist (a hard bounce) or the recipient marks your email as spam, MsGine adds the address to the suppression list and stops sending to it. If an API key's bounce rate reaches 5% or its complaint rate 0.1%, email sending on that key is suspended; contact support to restore it. Keep these rates low by sending only to people who expect your email and removing addresses that fail.