Connect your site or server to your newsletter: read and add subscribers, show your posts on your website, see your real numbers, and receive signed events.
Base URL
https://api.mujaz.io/api/v1
Version
v1
From the Pro plan. Bulk add and webhooks from Business. Feeds (RSS and JSON Feed) on every plan.
11. In Mujaz open Settings → API and press “Create key”. Only the account owner and Super Admins see this tab.
22. Choose what the key may do: “Website key” to show your posts, “Read only”, or “Read and write”. Then copy the key at once: it is shown in full only once.
33. Keep it in an environment variable on your server, then try this request. If you see your newsletter's name, the key works.
Send the key in the Authorization header only: Authorization: Bearer mjz_live_…. Cookies are ignored by the API, and a key in the address (?api_key=) is refused with KEY_IN_URL.
A key belongs to one account (one brand) for good. We store only its hash, never the key itself, so we can't show it again. After creation it appears as mjz_live_7Kp2Qx9a_…wxyz (its id and last four characters).
Key scopes
Key
Can reach
In a browser
Website key (posts:read)
GET /me and your published posts only
Allowed
Read only (read)
Every GET
Refused
Read and write (write)
Everything
Refused
The scope is chosen at creation and never changes; create a new key if you need another. A key can expire after 30, 90 or 365 days, or never (the default).
Any request with an Origin header (that is, from a page in a browser) is refused with BROWSER_NOT_ALLOWED, except a Website key on /me and /posts. A key pasted into a web page fails at once, before it can be stolen.
If a key leaks, revoke it in Settings → API: it stops within 30 seconds on all our servers. The account owner gets an email whenever a key is created, and the list shows each key's last use and the IP address it came from.
Two ways, both showing exactly what your public page shows: published, public posts only — never drafts, scheduled or hidden posts.
1. Your feed: no key, every plan
Every newsletter has an RSS 2.0 feed and a JSON Feed 1.1 with its latest 20 posts in full. Use it in WordPress, any feed reader or an automation tool. If your newsletter has its own live domain, the feed works there too.
text
https://www.mujaz.io/@mynewsletter/feed.xml # RSS 2.0
https://www.mujaz.io/@mynewsletter/feed.json # JSON Feed 1.1
https://newsletter.example.com/feed.xml # on your own domain
https://newsletter.example.com/feed.json
The feed updates within seconds of a new post, at most 10 minutes. Each post's id (mujaz:post:<id>) stays the same even if you change its address or your domain, so a reader never shows a post twice.
2. The posts API with a Website key: Pro and up
To build your own list of posts on your site, create a “Website key”. It can only read what is already published on your page, so it may sit in a web page: if it leaks, it exposes no subscriber data.
posts.html
<ul id="mujaz-posts"></ul>
<script>
// A Website key (posts:read) only. Never a Read-only or Read-and-write key.
const MUJAZ_WEBSITE_KEY = "mjz_live_7Kp2Qx9a_…";
fetch("https://api.mujaz.io/api/v1/posts?limit=5", {
headers: { Authorization: "Bearer " + MUJAZ_WEBSITE_KEY },
})
.then((res) => res.json())
.then(({ data }) => {
const list = document.getElementById("mujaz-posts");
for (const post of data) {
const item = document.createElement("li");
const link = document.createElement("a");
link.href = post.url;
link.textContent = post.title; // textContent, never innerHTML
item.dir = post.language === "ar" ? "rtl" : "ltr";
item.appendChild(link);
list.appendChild(item);
}
});
</script>
Every call counts toward your account's per-minute limit (60 on Pro, 300 on Business), and every visitor who opens the page makes one. On a busy site, fetch the posts on your server and cache them for a few minutes, or use the feed.
Every /posts answer carries an attribution field: the badge text in Arabic and English (textAr, text), its link url to your public page, and a ready line (lineAr, line). contentHtml, when present, ends with that line in a <p>.
Every error has the same shape: a stable code to build on, a message in English and Arabic you can show your user, and the request id to quote if you contact support.
json
{
"status": "error",
"code": "KEY_INVALID",
"message": "This API key isn't valid. Check that you copied all of it.",
"messageAr": "مفتاح API هذا غير صالح. تأكد أنك نسخته كاملًا.",
"requestId": "req_4f1c09a2b7d3e811"
}
Validation errors (VALIDATION_FAILED) add errors, one per problem field. Unknown fields are errors too: firstname instead of firstName is refused, never silently dropped.
The limit is per account, not per key: two keys don't double it. Each brand has its own. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds). Over the limit you get 429 RATE_LIMITED with Retry-After: wait that many seconds, then retry.
20 requests with a wrong key in a minute from one IP address block that address for 10 minutes (TOO_MANY_BAD_KEYS).
Send an Idempotency-Key header (1–100 characters: letters, digits and _.:-) with any POST, PATCH or DELETE. If the connection drops and you send the same request with the same key within 24 hours, you get the stored answer with Idempotent-Replayed: true and nothing runs twice. Recommended for create, bulk add and unsubscribe.
Lists return up to limit items (1–100, default 50; posts up to 50, default 20) with pagination. For the next page send nextCursor as cursor, until hasMore is false. Add includeTotal=true to get the total count.
Returns the account the key belongs to, the key itself, the plan and the limits. The simplest call to test a key. With a Website key you get the account, the key and limits.perMinute only.
graceUntil is set when your plan ended: keys keep working for 30 days and responses carry Mujaz-Api-Warning: plan-ended; until=<ISO>.
The same subscriber object in every answer. We never return a subscriber's IP address or confirmation tokens. The engagement numbers are the real stored counters, no estimates.
Works like your sign-up form: double opt-in when your form has it on (always for new accounts), and your welcome email once the person is active. If the person is already here you get 200 with created: false and only the lists and tags are added.
Request body (JSON)
email
stringrequired
The email address.
firstName / lastName
string ≤ 100optional
Their name.
language
ar | enoptional
Their language.
tags
string[] ≤ 20optional
Tags to add.
lists
id[] ≤ 20optional
Lists to add them to. “All Subscribers” is always added.
doubleOptIn
booleanoptional
Omitted: follows your form setting. true: stays pending and we send the confirmation email. A new account is always double opt-in and the answer says doubleOptInForced: true.
sendWelcome
booleanoptional
false skips your welcome email.
sourceRef
stringoptional
Your own reference, like the form's name.
updateExisting
booleanoptional
true replaces an existing person's name and language. Without it only empty ones are filled. The status never changes.
Someone who unsubscribed, bounced or complained can't be brought back through the API (OPTED_OUT), nor can suppressed addresses (SUPPRESSED). Coming back is the reader's own choice.
Confirmation emails caused by the API are capped at 200 an hour and 1,000 a day. Past that the person is still created pending with no email, and the answer says confirmationWithheld: true.
Unsubscribes and suppresses the address against being re-added, as in the dashboard. Repeating it is safe. Works even while the account is under review: an opt-out never waits.
For privacy requests. Removed from every list, then deleted for good. Someone who opted out stays suppressed so they can't be re-added. Send suppress: true to also block an active address (“forget me and never mail me”).
Up to 1,000 people per call and 30 calls an hour. Works like a dashboard import, with all its checks: people are added active, with no confirmation or welcome email. Every row gets a result.
Real numbers only, from the same functions as your dashboard: nothing estimated, and a rate is null when there were no recipients (never a made-up 0%).
Bounces and complaints are distinct people, not attempts. unsubscribesSinceSend covers the whole account since the send: nothing ties an unsubscribe to one issue. An issue never sent returns zeros with sent: false.
By id or slug; an old slug or a short code finds the post too, and the answer carries the current slug. Always includes contentHtml: cleaned HTML (no scripts or inline styles), wrapped in the right dir and lang, with absolute links. Anything your page doesn't show returns 404.
A very large post (over 100 KB) or one built from your own HTML comes without contentHtml: show the excerpt and a link to url.
Mujaz sends your server a signed request for each event you care about: a new subscriber, a confirmation, an unsubscribe, a bounce, an import, or an issue sent.
Too many requests. Wait the seconds in Retry-After and try again.
TOO_MANY_BAD_KEYS
429
Too many requests with a wrong key from this address. Try again in 10 minutes.
BODY_TOO_LARGE
413
The request is too large. Send at most 1 MB.
JSON_REQUIRED
415
Send the body as JSON (Content-Type: application/json).
VALIDATION_FAILED
400
Some fields aren't valid. Details in errors.
NOT_FOUND
404
Not found (this includes another account's ids).
IDEMPOTENCY_IN_PROGRESS
409
A request with this Idempotency-Key is still running. Try again in a moment.
IDEMPOTENCY_KEY_REUSED
422
This Idempotency-Key was already used with a different request.
EMAIL_INVALID
400
This isn't a valid email address.
EMAIL_TYPO
400
This looks like a typo in the email domain. Check it.
EMAIL_DISPOSABLE
400
Disposable or temporary email addresses can't be added.
EMAIL_UNDELIVERABLE
400
This email domain can't receive mail. Check the address.
LIST_NOT_FOUND
404
One of these lists doesn't exist in this account.
OPTED_OUT
409
This person unsubscribed, bounced or complained, so they can't be brought back through the API.
SUPPRESSED
409
This address is suppressed and can't be added.
SUBSCRIBER_LIMIT
403
You've reached your plan's subscriber limit.
NEW_ACCOUNT_IMPORT_CAP
403
New accounts can hold up to 1,000 contacts in their first week. Contact support to verify your account and lift it.
API_INTAKE_LOOKS_PURCHASED
403
The addresses added through the API look purchased or scraped. Mujaz only sends to people who asked to hear from you. Contact [email protected] to review it.
IMPORT_LOOKS_PURCHASED
403
This batch looks purchased or scraped, so it wasn't imported.
BULK_TOO_LARGE
400
Send at most 1,000 people per call.
INTERNAL
500
Something went wrong on our side. Try again; with an Idempotency-Key a retry is safe.
First release: keys with three scopes, subscribers, lists and tags, stats, newsletters, posts, bulk add, signed webhooks, and RSS and JSON feeds.
Last checked:
We use cookies
We use cookies and similar technologies to enhance your experience, analyze site usage, and assist in our marketing efforts. By clicking "Accept All", you consent to our use of cookies. Learn more