Authentication

Every request needs an API key. Make one on the API keys page in the console, and send it as a Bearer token.

Authorization: Bearer $NOTIX_API_KEY

Keep the key on your server. Never put it in a browser or a mobile app.

Key permissions

A key carries one of four permissions. The console names them as in brackets. API keys and permissions shows where each is made.

Each endpoint page names the permission it needs. In the OpenAPI document, each operation carries it as x-notix-key-access.

Give the service that only sends a sending access key. Keep full access keys for the jobs that manage domains and contacts.

Keys restricted to one domain

A key can also be restricted to one sending domain. It then sends only from that domain, and reads only that domain's emails, analytics and inbound mail.

A restricted key cannot:

• add domains;
• send SMS or one-time codes;
• use webhooks, because they carry every domain's events;
• read the team's ledger, receipts, invoices or plan (it can read the usage and the price list);
• enrol contacts into an automation that sends from another domain;
• create or change an automation with an email from another domain.

Those calls answer 403 DOMAIN_PINNED.

Contacts, contact books, templates and segments belong to the whole team. A restricted key still reaches them.

Shared inbox

In the shared inbox (/v1/inbound/conversations, /v1/inbound/inboxes and /v1/inbound/status) a key acts as the person who created it, as they are on the team today. That means their inboxes, their unread marks, and their name on notes and replies.

A key whose creator left the team answers 403 FORBIDDEN. So does a key made before Notix recorded who made each key.

What each key can do:

• A full access key may reply, assign, set status, add notes, mark read or unread, and act on an unsubscribe request.
• Read only keys only read.
• Sending access keys reach none of it.

A reply is a real send. The key's approval policy and caps apply. A key restricted to one domain sees only the inboxes that receive on that domain, and replies from that domain. Teammates' addresses in an inbox's members list go only to full access keys.

The other inbound reads (received messages, a conversation's thread and the summary) follow the same rule:

• A key made by a member reads only that member's inboxes.
• A key made by an admin or the owner reads every inbox.
• A key made before Notix recorded who made it still reads the whole team's mail.

Draft broadcasts

Changing a draft broadcast, creating one from a template and copying a template into one need one of these:

• a full access key, whoever on the team made it (as creating a broadcast does);
• a live AI key, which changes only the drafts it created itself, and may not set cc or bcc, or a reply-to off its domain, on any broadcast.

A raw HTML body makes the draft an API broadcast. The dashboard then shows its body read-only.

Only a draft changes. A broadcast that is not a draft, or that was edited or scheduled while your change was being saved, answers 409 CONFLICT, and nothing is written.

A broadcast's review checks and preview are reads. Its recipient list needs a full access key that is not restricted to one domain.

Billing

Billing (/v1/billing) is read only. No endpoint moves money or changes a plan.

• The wallet ledger, receipts, invoices and the plan need a full access or read only key made by someone who is a team admin today, as the billing page is for admins.
• A key made by a member, or before Notix recorded who made each key, answers 403 FORBIDDEN. Every such read is in the key's audit log.
• The usage and the price list are open to full access, read only and live AI keys, restricted to one domain or not. A caller can check that a send fits your limits.
• Sending access keys reach none of it.

SMS and one-time code reads

Full access and read only keys read these:

• the SMS overview, figures and code template (/v1/sms/overview, /v1/sms/stats, /v1/sms/template);
• the list and figures of one-time codes (GET /v1/verify, /v1/verify/stats).

No answer ever holds a code. Phone numbers are masked to their last four digits.

Changing the code template needs a full access key made by someone who is a team admin today, as the SMS page lets only admins change it. A key made by a member, or before Notix recorded who made each key, answers 403 FORBIDDEN. A template with a link in it answers 400.

The wallet balance and the spend are only given to a key made by a team admin.

Sending access and live AI keys, and keys restricted to one domain, reach none of these.

Template library

The starter template library (GET /v1/templates/library) is Notix's own content. Full access, read only and live AI keys read it.

Copying a library entry into your templates (POST /v1/templates/from-library) and duplicating a template (POST /v1/templates/{templateId}/duplicate) each create a new template and never change the original. So full access and live AI keys may do both, restricted to one domain or not, as templates carry no domain.

A live AI key still cannot change or delete a template. Sending access keys reach none of these.

Domain settings

Changing a domain's click and open tracking (PATCH /v1/domains/{id}) needs a full access key.

Asking Notix to review a paused domain (POST /v1/domains/{id}/review) also needs a key made by someone who is a team admin today, as only admins can press Request review in the console. A key made by a member, or before Notix recorded who made each key, answers 403 FORBIDDEN.

A review only asks. The domain stays paused until Notix resumes it. Asking again during the same pause answers the first request's time.

A key restricted to one domain may touch only that domain. Any other answers 404. Read only, sending access and live AI keys reach neither call, and Notix's own domains cannot be changed.

Forwarding

Forwarding (/v1/forwarding-rules and /v1/forwarding-destinations) sends your received mail outside Notix. Creating, changing and deleting rules and forwarding addresses needs a full access key made by someone who is a team admin today. A key made by a member, or before Notix recorded who made each key, answers 403 FORBIDDEN.

Full access and read only keys read rules, addresses and the forward log. The address tester needs a full access key. A key restricted to one domain sees and changes only the rules on its domain, and answers 403 DOMAIN_PINNED on the forwarding addresses. Sending access and live AI keys reach none of it.

Deleting a key pauses the forwarding rules it created; pausing a key does not. See Forward received emails.

Live AI keys

Connect your AI in the console makes one more kind of key for an AI app.

A live AI key is restricted to one verified domain. It can:

• read your data, except SMS, one-time codes, inbound mail, forwarding and billing (it can read the usage and the price list);
• send email from its domain, check deliverability, and enrol one contact in an automation;
• create templates (not change existing ones);
• create and update contact lists, contacts and segments;
• create (also from a template), duplicate, approve (with the code a person was emailed) and pause broadcasts;
• change a draft broadcast it created itself, or copy a template into one;
• schedule a draft broadcast, or reschedule one it scheduled itself;
• enrol a batch of contacts in an automation, and pause an automation;
• reschedule or cancel a scheduled email it sent itself;
• add addresses to the suppression list, at most its "ask me first" number a day.

A live AI key cannot:

• delete anything;
• change an existing template, or a broadcast it did not create;
• resume a broadcast or an automation;
• create, change, turn on, archive or test an automation;
• send SMS or one-time codes;
• use the SendGrid or Resend compatible endpoints;
• read inbound mail, use the shared inbox or use forwarding;
• use webhooks;
• read the ledger, receipts, invoices or plan;
• change domains, billing, your team or API keys.

Those answer 403 SCOPE_DENIED.

It also cannot set up double opt-in, add contacts to a list that uses it, or add contacts to a list whose automations send from another domain. Those answer 403 FORBIDDEN.

Past its daily suppression allowance it answers 403 FORBIDDEN. When the allowance cannot be checked it answers 503 SERVICE_UNAVAILABLE. Try again shortly.

A broadcast it schedules for more people than its "ask me first" number needs a person's approval. A direct send or batch to more people than that number is refused with 403 FORBIDDEN. Use a broadcast instead. Its daily limit stops it for the day.

Replace keys made before Notix recorded who made them

Older keys do not record who made them. Such a key answers 403 FORBIDDEN in the shared inbox, and some reads (inbound mail, billing, the SMS template) treat it differently from a key with a known maker. Make a new key on the API keys page, move your service to it, then delete the old one. The new key acts as you, with your role on the team today.

Check a key

Check an API key tells you which team and permission a key has. Read this key's limits returns its rate limits, caps and approval policy.

curl https://app.usenotix.dev/api/v1/auth/check \
  -H "Authorization: Bearer $NOTIX_API_KEY"