Create a forwarding rule
Forward email received at matching addresses to confirmed forwarding addresses, a webhook, or both.
https://app.usenotix.dev/api/v1/forwarding-rulesNeeds a full access key. Sending access keys cannot call this. Key permissions lists the extra rules some calls have.
Forward email received at matching addresses to confirmed forwarding addresses, a webhook, or both.
{
"name": "Billing to finance",
"pattern": "billing@reply.acmepay.com",
"destinationIds": ["clx9f2k3l0002qz8a7b6c5d4e"],
"fromAddress": "support@acmepay.com",
"priority": 10
}
The answer is the rule. An address that is not confirmed yet is kept on the rule and gets forwards once it is.
Patterns
| Pattern | Matches |
|---|---|
billing@reply.acmepay.com | That address only. |
orders-*@reply.acmepay.com | Addresses that start with orders-. |
*@reply.acmepay.com | Every address on the domain. Send confirmCatchAll: true with it. |
A pattern never matches a subdomain. Notix delivers orders+eu@ to orders@, so a pattern cannot contain +. On the shared Notix domain, a pattern that matches none of your inbox addresses is refused. On your own receiving domain every address is received, so any pattern on it is accepted while the domain is receiving. A wildcard or prefix pattern there needs fromAddress, and creating one, or widening a rule to one, emails every team admin.
How a rule forwards
When a message arrives at an address your team receives on, Notix stores it and sends email.received first. Then it finds the first rule that is on and matches one of the addresses the message was sent to, trying lower priority numbers first. That one rule forwards the message to each of its confirmed addresses.
Each forward is a normal email from your team:
- sent from
fromAddress(or the receiving address when it is on a verified sending domain), never as the original sender; - with
Reply-Toset to the original sender, so a reply goes to them; - with the original subject, text, HTML and attachments;
- with the header
X-Notix-Forwarded, so a forwarded message is never forwarded again; - with a one-click "stop forwarding" link (List-Unsubscribe), so the person at the address can stop it;
- never with click or open tracking.
When Notix cannot confirm the sender (DMARC did not pass, or the spam check could not tell), the forward still goes, but its subject starts with [Unverified sender], the sender's display name is left out and there is no Reply-To. Attachments are forwarded only when the virus check passed and they fit what one email can carry (10 files, 7 MB each, 10 MB in total); otherwise the forward goes without them and says which were left out.
Each forward counts as one transactional email against your plan, like POST /v1/emails. Receiving is free. Bounces and complaints on forwards do not count toward your domain's reputation pause; forwarding has its own, at the same limits, which pauses every rule of the team and starts again from the next day after you resume. Each forward carries a stop-forwarding link in its headers that anyone holding the forward can use.
Notix does not forward spam, messages with a virus, automatic replies, the same Message-ID twice within 24 hours, or to an address on a domain you also receive on (unless allowChaining is true). A rule that forwards more than 100 messages in 10 minutes is paused and your admins are emailed. Over a rate limit, a forward waits and is tried again for about 15 minutes before it is recorded as skipped. Every outcome is in the rule's log.
Who can call it
A full access key made by a team admin, as on the dashboard. Every refusal is 403:
| Code | Why |
|---|---|
SCOPE_DENIED | The key is not a full access key (send-only, read only or live AI). |
FORBIDDEN | The key was made by a team member without admin rights, or before Notix recorded who made each key. Create a new key as a team admin. |
DOMAIN_PINNED | The key is limited to one domain and the rule is on another, or the rule sends to a webhook. |
Body parameters
A label for the rule.
At most 80 characters.
The receiving addresses the rule forwards: one address (billing@reply.acmepay.com), every address on a domain (*@reply.acmepay.com, needs confirmCatchAll), or addresses that start with a prefix (orders-*@reply.acmepay.com). The domain must be one your team receives email on.
At least 3 characters. At most 320 characters.
Up to 10 forwarding address ids from POST /v1/forwarding-destinations. Only confirmed addresses receive forwards.
Also send each matching message to this webhook of yours as an email.received event, whatever events it subscribes to. Not for a key limited to one domain.
At most 64 characters. Can be null.
The address forwards are sent from, on one of your verified sending domains. Leave it out to send from the receiving address, which then has to be on a verified sending domain too. Forwards are never sent as the original sender, who is set as Reply-To.
At most 254 characters. Can be null.
Text put in front of each forwarded subject. Off by default.
At most 40 characters. Can be null.
Allow forwarding addresses on a domain your team also receives on. Off by default, because that can start a loop.
true (the default): forward each message exactly as it arrived. false: send it like an email client's forward, with note on top, then a Forwarded message block (From, Date, Subject, To, Cc) above the original, and Fwd: on the subject. Attachments go either way.
Plain text shown above the Forwarded message block when passthrough is false. At most 2,000 characters; ignored when passthrough is true.
At most 2,000 characters. Can be null.
Whether the rule forwards. A rule that is off is skipped.
Lower numbers are tried first. The first matching rule that is on forwards the message. Default 100.
Minimum 0. Maximum 10000.
Required as true for a pattern like *@reply.acmepay.com, which forwards every email the domain receives.
Headers
Bearer followed by your API key.
Errors
The body is not valid, or the rule is refused: see the message (pattern, domain, sender, loop).
`SCOPE_DENIED`: not a full access key. `FORBIDDEN`: the key was made by a team member without admin rights, or before Notix recorded who made each key. `DOMAIN_PINNED`: the pattern or the webhook is outside the key's one domain.
A destination or the webhook is not the team's.
The team already has a rule for this pattern.
The team changed rules 30 times in the last minute.
Notix cannot count the team's calls just now; try again shortly.
Every error has the same shape. See all error codes.
curl -X POST "https://app.usenotix.dev/api/v1/forwarding-rules" \
-H "Authorization: Bearer $NOTIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Billing to finance",
"pattern": "billing@reply.acmepay.com"
}'
import { Notix } from "notix-js";
const notix = new Notix(process.env.NOTIX_API_KEY);
const { data, error } = await notix.forwarding.createRule({
name: "Billing to finance",
pattern: "billing@reply.acmepay.com",
destinationIds: ["clx9f2k3l0002qz8a7b6c5d4e"],
fromAddress: "support@acmepay.com",
});
{
"id": "cm1x8f3k20001qz7v5b9d2e4a",
"name": "Acme",
"pattern": "billing@reply.acmepay.com",
"patternType": "EXACT",
"receivingDomain": "reply.acmepay.com",
"destinations": [
{
"id": "cm1x8f3k20001qz7v5b9d2e4a",
"email": "customer@example.com",
"status": "PENDING"
}
],
"webhookId": "cm1x8f3k20001qz7v5b9d2e4a",
"fromAddress": "string",
"subjectPrefix": "Your receipt for order 4471",
"allowChaining": true,
"passthrough": true,
"note": "string",
"active": true,
"priority": 1,
"paused": true,
"pausedAt": "string",
"pauseReason": "string",
"createdAt": "string",
"updatedAt": "string"
}