Developers

The Mujaz API

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.

Quick start

  1. 1. In Mujaz open Settings → API and press “Create key”. Only the account owner and Super Admins see this tab.
  2. 2. 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.
  3. 3. Keep it in an environment variable on your server, then try this request. If you see your newsletter's name, the key works.
bash
export MUJAZ_API_KEY="mjz_live_7Kp2Qx9a_…"

curl https://api.mujaz.io/api/v1/me \
  -H "Authorization: Bearer $MUJAZ_API_KEY"

Authentication

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

KeyCan reachIn a browser
Website key (posts:read)GET /me and your published posts onlyAllowed
Read only (read)Every GETRefused
Read and write (write)EverythingRefused

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.

Show your posts on your website

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.

Attribution

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>.

badge.html
<ul id="mujaz-posts"></ul>
<p id="mujaz-badge"></p>
<script>
  fetch("https://api.mujaz.io/api/v1/posts?limit=5", {
    headers: { Authorization: "Bearer " + MUJAZ_WEBSITE_KEY },
  })
    .then((res) => res.json())
    .then(({ data, attribution }) => {
      // … your list of posts (see above) …
      const badge = document.createElement("a");
      badge.href = attribution.url;
      badge.target = "_blank";
      badge.rel = "noopener";
      badge.textContent = document.documentElement.lang === "ar" ? attribution.textAr : attribution.text;
      document.getElementById("mujaz-badge").appendChild(badge);
    });
</script>

Rather not build it? Settings → Form Integration → Embed code has a ready box with your latest issues and a subscribe form, badge included.

Errors

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.

json
{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "Some fields aren't valid.",
  "messageAr": "بعض الحقول غير صالحة.",
  "errors": [
    { "field": "firstname", "code": "unknown", "message": "…", "messageAr": "…" }
  ],
  "requestId": "req_…"
}

Rate limits

PlanRequests per minuteActive keysBulk addWebhooks
Pro602——
Business and Scale30010Up to 1,000 per call, 30 calls an hourUp to 5 addresses

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).

Safe retries (idempotency)

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.

bash
curl -X POST https://api.mujaz.io/api/v1/subscribers \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-2026-11-18-reader-example-com" \
  -d '{ "email": "[email protected]" }'
  • The same key with a different request → 422 IDEMPOTENCY_KEY_REUSED.
  • The same key while the first request is still running → 409 IDEMPOTENCY_IN_PROGRESS. Retry in a moment.
  • An error on our side (5xx) is not stored, so a retry runs fresh.

Pagination

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.

json
{
  "status": "success",
  "data": [ … ],
  "pagination": { "nextCursor": "eyJpZCI6IjY3NDBjMWYy…", "hasMore": true }
}

A cursor doesn't slow down page after page, and doesn't repeat or skip anyone added while you page. For a full oldest-first sync use order=asc.

Account

Your account and key

GET/me
Key needed: Website key

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>.

Request
curl https://api.mujaz.io/api/v1/me \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": {
    "workspace": {
      "id": "6720f0a1b2c3d4e5f6a7b8c9",
      "name": "نشرتي",
      "handle": "mynewsletter",
      "isBrand": false,
      "publicUrl": "https://www.mujaz.io/@mynewsletter"
    },
    "key": { "keyId": "7Kp2Qx9a", "name": "WordPress", "scope": "write", "createdAt": "2026-11-18T09:00:00.000Z", "expiresAt": null },
    "plan": "pro",
    "tier": "pro",
    "limits": { "perMinute": 60, "bulk": false, "webhooks": false },
    "graceUntil": null
  }
}

Subscribers

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.

List subscribers

GET/subscribers
Key needed: Read only

Subscribers newest first (or oldest first), with filters.

Query parameters

status
active,pending,unsubscribed,bounced,complainedoptional
One or more statuses, comma-separated.
list
idoptional
Subscribers in this list.
tag
stringoptional
Subscribers with this tag.
language
ar | enoptional
The subscriber's language.
email
stringoptional
One exact email address.
createdAfter / createdBefore
ISO 8601optional
Bounds on the date they joined.
order
desc | ascoptional
desc (default) newest first; asc for an oldest-first sync.
limit
1–100optional
Items per page (default 50).
cursor
stringoptional
nextCursor from the previous page.
includeTotal
trueoptional
Adds total to pagination.
Request
curl "https://api.mujaz.io/api/v1/subscribers?status=active&limit=2" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": [
    {
      "id": "6740c1f2a9b8e4d3c2b1a0f9",
      "email": "[email protected]",
      "firstName": "Lina",
      "lastName": "",
      "language": "ar",
      "status": "active",
      "tags": ["vip"],
      "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
      "source": "api",
      "sourceRef": "wordpress-footer",
      "createdAt": "2026-11-18T10:00:00.000Z",
      "updatedAt": "2026-11-18T10:00:00.000Z",
      "unsubscribedAt": null,
      "confirmationSentAt": null,
      "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
    },
    { "id": "…", "email": "…", "…": "…" }
  ],
  "pagination": { "nextCursor": "eyJpZCI6…", "hasMore": true }
}

Errors specific to this call

Get a subscriber

GET/subscribers/{idOrEmail}
Key needed: Read only

By id (24 characters) or by email address (URL-encoded: @ becomes %40).

Request
curl https://api.mujaz.io/api/v1/subscribers/reader%40example.com \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": {
    "id": "6740c1f2a9b8e4d3c2b1a0f9",
    "email": "[email protected]",
    "firstName": "Lina",
    "lastName": "",
    "language": "ar",
    "status": "active",
    "tags": ["vip"],
    "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
    "source": "api",
    "sourceRef": "wordpress-footer",
    "createdAt": "2026-11-18T10:00:00.000Z",
    "updatedAt": "2026-11-18T10:00:00.000Z",
    "unsubscribedAt": null,
    "confirmationSentAt": null,
    "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
  }
}

Errors specific to this call

Add a subscriber

POST/subscribers
Key needed: Read and write

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.

Request
curl -X POST https://api.mujaz.io/api/v1/subscribers \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wp-signup-8812" \
  -d '{
    "email": "[email protected]",
    "firstName": "Lina",
    "language": "ar",
    "tags": ["vip"],
    "sourceRef": "wordpress-footer"
  }'
Response
{
  "status": "success",
  "data": {
    "created": true,
    "doubleOptInForced": false,
    "confirmationWithheld": false,
    "subscriber": {
      "id": "6740c1f2a9b8e4d3c2b1a0f9",
      "email": "[email protected]",
      "firstName": "Lina",
      "lastName": "",
      "language": "ar",
      "status": "active",
      "tags": ["vip"],
      "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
      "source": "api",
      "sourceRef": "wordpress-footer",
      "createdAt": "2026-11-18T10:00:00.000Z",
      "updatedAt": "2026-11-18T10:00:00.000Z",
      "unsubscribedAt": null,
      "confirmationSentAt": null,
      "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
    }
  }
}

Update a subscriber

PATCH/subscribers/{id}
Key needed: Read and write

At least one field. The email and status can't be changed: changing the address or coming back after unsubscribing is the reader's own action.

Request body (JSON)

firstName / lastName / language
stringoptional
Replace the current values.
tags
string[]optional
Replaces every tag.
addTags / removeTags
string[]optional
Adds or removes tags.
addLists / removeLists
id[]optional
Adds to or removes from lists.
Request
curl -X PATCH https://api.mujaz.io/api/v1/subscribers/6740c1f2a9b8e4d3c2b1a0f9 \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "addTags": ["webinar-2026"] }'
Response
{
  "status": "success",
  "data": { "id": "6740c1f2a9b8e4d3c2b1a0f9", "tags": ["vip", "webinar-2026"], "…": "…" }
}

Errors specific to this call

Unsubscribe

POST/subscribers/{id}/unsubscribe
Key needed: Read and write

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.

Request body (JSON)

reason
string ≤ 200optional
The reason (optional).
Request
curl -X POST https://api.mujaz.io/api/v1/subscribers/6740c1f2a9b8e4d3c2b1a0f9/unsubscribe \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Asked by email" }'
Response
{
  "status": "success",
  "data": { "id": "6740c1f2a9b8e4d3c2b1a0f9", "status": "unsubscribed", "unsubscribedAt": "2026-11-18T11:00:00.000Z", "…": "…" }
}

Errors specific to this call

Delete a subscriber

DELETE/subscribers/{id}
Key needed: Read and write

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”).

Request body (JSON)

suppress
booleanoptional
Also suppress the address.
Request
curl -X DELETE https://api.mujaz.io/api/v1/subscribers/6740c1f2a9b8e4d3c2b1a0f9 \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "suppress": true }'
Response
{ "status": "success", "data": { "deleted": true, "suppressed": true } }

Errors specific to this call

Bulk add

POST/subscribers/bulk
Key needed: Read and writeBusiness

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.

Request body (JSON)

subscribers
[{ email, firstName, lastName, language, tags }] ≤ 1000required
The people.
lists
id[]optional
Lists to add everyone to.
language
ar | enoptional
The language for rows without one.
updateExisting
booleanoptional
Update people already here.

Each row's result is one of created, existed, updated, skipped, leftOut (over your plan limit) and error.

Request
curl -X POST https://api.mujaz.io/api/v1/subscribers/bulk \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2026-11-18" \
  -d '{
    "subscribers": [
      { "email": "[email protected]", "firstName": "Sami" },
      { "email": "b@example" }
    ],
    "lists": ["6731aa04c2e9d8f7b6a5e4d3"]
  }'
Response
{
  "status": "success",
  "data": {
    "imported": 1, "updated": 0, "alreadyExisted": 0, "skipped": 1, "errors": 0,
    "truncated": false, "leftOut": 0, "limit": null,
    "results": [
      { "row": 1, "email": "[email protected]", "result": "created", "id": "6740c1f2a9b8e4d3c2b1a0fa" },
      { "row": 2, "email": "b@example", "result": "skipped", "code": "EMAIL_INVALID" }
    ]
  }
}

Lists and tags

Lists

GET/lists
Key needed: Read only

Your lists with their live member count (active + pending). isDefault is “All Subscribers”.

Request
curl https://api.mujaz.io/api/v1/lists \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": [
    { "id": "6731aa04c2e9d8f7b6a5e4d3", "name": "All Subscribers", "description": "", "languageTag": null, "isDefault": true, "subscriberCount": 3100, "createdAt": "2026-03-02T12:00:00.000Z" }
  ]
}

Tags

GET/tags
Key needed: Read only

Every tag with how many people carry it.

Request
curl https://api.mujaz.io/api/v1/tags \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{ "status": "success", "data": [ { "tag": "vip", "count": 120 } ] }

Stats and newsletters

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%).

Account numbers

GET/stats
Key needed: Read only

Subscribers and email over a period.

Query parameters

period
7d | 30d | 90d | 1yoptional
The period (default 30d).
Request
curl "https://api.mujaz.io/api/v1/stats?period=30d" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": {
    "period": "30d", "from": "2026-10-19T00:00:00.000Z", "to": "2026-11-18T00:00:00.000Z", "periodClamped": null,
    "subscribers": { "total": 3100, "active": 2950, "pending": 150, "unsubscribed": 210, "bounced": 40, "complained": 2,
                     "newInPeriod": 320, "unsubscribedInPeriod": 18 },
    "emails": { "newslettersSent": 4, "recipients": 11800, "delivered": 11690, "uniqueOpens": 5200, "uniqueClicks": 900,
                "openRate": 44.5, "clickRate": 7.7, "bounces": 60, "complaints": 1 }
  }
}

Newsletters

GET/newsletters
Key needed: Read only

Your issues without their content. publicUrl is set when the issue is published and public. Welcome emails are left out.

Query parameters

status
sent | scheduled | draftoptional
Default sent.
limit
1–100optional
Items per page (default 50).
cursor
stringoptional
nextCursor from the previous page.
Request
curl "https://api.mujaz.io/api/v1/newsletters?status=sent&limit=10" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": [
    { "id": "6741d0e3b8a7f6e5d4c3b2a1", "title": "…", "subject": "…", "slug": "my-post", "status": "sent",
      "format": "article", "webOnly": false, "sentAt": "2026-11-15T09:00:00.000Z", "scheduledAt": null,
      "publishedAt": "2026-11-15T09:00:00.000Z", "recipients": 2950,
      "publicUrl": "https://www.mujaz.io/@mynewsletter/my-post" }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

Get a newsletter

GET/newsletters/{id}
Key needed: Read only

The same object as in the list.

Request
curl https://api.mujaz.io/api/v1/newsletters/6741d0e3b8a7f6e5d4c3b2a1 \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{ "status": "success", "data": { "id": "6741d0e3b8a7f6e5d4c3b2a1", "status": "sent", "…": "…" } }

Errors specific to this call

Newsletter stats

GET/newsletters/{id}/stats
Key needed: Read only

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.

Request
curl https://api.mujaz.io/api/v1/newsletters/6741d0e3b8a7f6e5d4c3b2a1/stats \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": {
    "recipients": 2950, "delivered": 2921, "opens": 2400, "uniqueOpens": 1300, "clicks": 410, "uniqueClicks": 260,
    "bounces": 12, "complaints": 0, "openRate": 44.5, "clickRate": 8.9,
    "unsubscribesSinceSend": 5, "unsubscribesScope": "workspace"
  }
}

Errors specific to this call

Posts

Only what your public page shows: published and public, in the same order. Any key may read them, and a Website key may read them from a browser too.

List posts

GET/posts
Key needed: Website key

Newest first. Any other filter (like status) is refused: the API shows only what the feed shows.

Query parameters

limit
1–50optional
Default 20.
cursor
stringoptional
nextCursor from the previous page.
format
article | newsletteroptional
Articles or newsletters only.
includeContent
trueoptional
Adds contentHtml to each post; limit is then at most 10.
Request
curl "https://api.mujaz.io/api/v1/posts?limit=5" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": [
    {
      "id": "6741d0e3b8a7f6e5d4c3b2a1",
      "slug": "my-post",
      "title": "…",
      "subtitle": "…",
      "excerpt": "…",
      "format": "article",
      "language": "ar",
      "publishedAt": "2026-11-15T09:00:00.000Z",
      "updatedAt": "2026-11-15T09:30:00.000Z",
      "url": "https://www.mujaz.io/@mynewsletter/my-post",
      "shortUrl": "https://www.mujaz.io/@mynewsletter/k3x9",
      "coverImage": { "url": "https://img.mujaz.io/…webp", "alt": "…" },
      "readingMinutes": 6,
      "categories": ["…"],
      "author": { "name": "…", "role": "…", "avatar": "https://…" }
    }
  ],
  "pagination": { "nextCursor": "eyJjIjoiMjAyNi0xMS0xNVQwOTowMDow…", "hasMore": true },
  "attribution": {
    "text": "Powered by Mujaz",
    "textAr": "مدعوم بواسطة موجز",
    "url": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "subscribeUrl": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "line": "Written and sent with Mujaz. Subscribe: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "lineAr": "كُتبت وأُرسلت عبر موجز. اشترك: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution"
  }
}

Errors specific to this call

Get a post

GET/posts/{idOrSlug}
Key needed: Website key

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.

Request
curl https://api.mujaz.io/api/v1/posts/my-post \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
Response
{
  "status": "success",
  "data": {
    "id": "6741d0e3b8a7f6e5d4c3b2a1",
    "slug": "my-post",
    "title": "…",
    "subtitle": "…",
    "excerpt": "…",
    "format": "article",
    "language": "ar",
    "publishedAt": "2026-11-15T09:00:00.000Z",
    "updatedAt": "2026-11-15T09:30:00.000Z",
    "url": "https://www.mujaz.io/@mynewsletter/my-post",
    "shortUrl": "https://www.mujaz.io/@mynewsletter/k3x9",
    "coverImage": { "url": "https://img.mujaz.io/…webp", "alt": "…" },
    "readingMinutes": 6,
    "categories": ["…"],
    "author": { "name": "…", "role": "…", "avatar": "https://…" },
    "contentHtml": "<div dir=\"rtl\" lang=\"ar\">…</div><p dir=\"rtl\" lang=\"ar\">كُتبت وأُرسلت عبر موجز. اشترك: <a href=\"…\">…</a></p>"
  },
  "attribution": {
    "text": "Powered by Mujaz",
    "textAr": "مدعوم بواسطة موجز",
    "url": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "subscribeUrl": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "line": "Written and sent with Mujaz. Subscribe: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "lineAr": "كُتبت وأُرسلت عبر موجز. اشترك: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution"
  }
}

Errors specific to this call

Webhooks

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.

Webhooks reference

All error codes

CodeHTTPMeaning
KEY_MISSING401Add your API key in the Authorization header: Bearer mjz_live_…
KEY_INVALID401This API key isn't valid. Check that you copied all of it.
KEY_REVOKED401This API key was revoked. Create a new one in Settings → API.
KEY_EXPIRED401This API key expired. Create a new one in Settings → API.
KEY_IN_URL400Send the API key in the Authorization header, never in the address.
BAD_HEADER400This header can't be used with the API.
BROWSER_NOT_ALLOWED403This key works only from your server. In a web page use your feed or a website key.
API_OFF403The API isn't available on this account yet.
PLAN_TOO_LOW403The API starts from the Pro plan. Upgrade to use it.
UNPAID_TRIAL403The API opens after your first payment. It isn't available during a trial.
BUSINESS_FEATURE403Bulk add and webhooks start from the Business plan.
SCOPE_REQUIRED403The key's scope doesn't cover this call: a read key can't write, and a website key can only read posts.
WORKSPACE_PAUSED403This account is under review, so the API can only read for now.
WORKSPACE_SUSPENDED403This account is suspended. Contact [email protected].
ACCOUNT_PENDING_DELETION403The account is scheduled for deletion.
RATE_LIMITED429Too many requests. Wait the seconds in Retry-After and try again.
TOO_MANY_BAD_KEYS429Too many requests with a wrong key from this address. Try again in 10 minutes.
BODY_TOO_LARGE413The request is too large. Send at most 1 MB.
JSON_REQUIRED415Send the body as JSON (Content-Type: application/json).
VALIDATION_FAILED400Some fields aren't valid. Details in errors.
NOT_FOUND404Not found (this includes another account's ids).
IDEMPOTENCY_IN_PROGRESS409A request with this Idempotency-Key is still running. Try again in a moment.
IDEMPOTENCY_KEY_REUSED422This Idempotency-Key was already used with a different request.
EMAIL_INVALID400This isn't a valid email address.
EMAIL_TYPO400This looks like a typo in the email domain. Check it.
EMAIL_DISPOSABLE400Disposable or temporary email addresses can't be added.
EMAIL_UNDELIVERABLE400This email domain can't receive mail. Check the address.
LIST_NOT_FOUND404One of these lists doesn't exist in this account.
OPTED_OUT409This person unsubscribed, bounced or complained, so they can't be brought back through the API.
SUPPRESSED409This address is suppressed and can't be added.
SUBSCRIBER_LIMIT403You've reached your plan's subscriber limit.
NEW_ACCOUNT_IMPORT_CAP403New accounts can hold up to 1,000 contacts in their first week. Contact support to verify your account and lift it.
API_INTAKE_LOOKS_PURCHASED403The 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_PURCHASED403This batch looks purchased or scraped, so it wasn't imported.
BULK_TOO_LARGE400Send at most 1,000 people per call.
INTERNAL500Something went wrong on our side. Try again; with an Idempotency-Key a retry is safe.

Changelog

  • v1

    First release: keys with three scopes, subscribers, lists and tags, stats, newsletters, posts, bulk add, signed webhooks, and RSS and JSON feeds.

Last checked: