What does a 403 error mean?

A 403 Forbidden response from the AgentMail API means your request was rejected. This can happen for several reasons, and the fix depends on the cause.

Check the response body first. Application-level 403s carry a machine-readable code, a fix describing the concrete next action, and a docs link into the Error Reference — the fix usually resolves the issue directly. The one exception is a bare {"message":"Forbidden"} with none of those fields: that response comes from the API gateway rejecting your credential before it reaches the API, which almost always means cause 1 below.

1. Incorrect API key

The most common cause. Your API key may be missing, incomplete, or invalid.

How to fix:

• Go to the AgentMail Console and generate a new API key
• When you generate a new key, copy the entire key immediately. It is only shown once and starts with am_
• Make sure you are passing the key in the Authorization header as Bearer am_...

1
import { AgentMailClient } from "agentmail";
2
3
// Make sure the full key is copied, no trailing spaces or missing characters
4
const client = new AgentMailClient({ apiKey: "am_..." });

2. Accessing a resource you do not own

Accessing an inbox, message, thread, or domain that belongs to a different organization — or one outside your key’s pod or inbox scope — returns a 404 with code: "not_found", not a 403: resources outside your credential’s scope are deliberately indistinguishable from ones that don’t exist. The 403 you can hit in this family is using an inbox-scoped key on a pod route.

How to fix: Verify that the inbox_id, message_id, thread_id, or domain_id in your request actually belongs to your account and is within your key’s scope. See not_found in the Error Reference.

3. Missing required parameters

Some endpoints return a 403 when required path parameters are missing or malformed. For example, calling /v0/inboxes//messages with an empty inbox_id may return 403 instead of 400.

How to fix: Double check that all required path parameters are filled in correctly.

4. Sending to a suppressed address

AgentMail automatically suppresses addresses that have previously bounced, been rejected, or filed a spam complaint. If you try to send to a suppressed address, the API returns a 403 with code: "message_rejected"; the fix names the matched block entry and the exact remedy (deletable entries get a DELETE path; suppression entries added from bounces or complaints are read-only and go through support review).

How to fix: Read the fix field on the response. See message_rejected in the Error Reference and Emails bouncing for how suppression works.

5. Your API key lacks a permission

API keys can be created with granular permissions (for example, a key that can read messages but not send them). A denial from a permission gate returns code: "missing_permission", and the fix names the exact missing permission and how to obtain it — including when a new key at the same scope cannot help (the permission is outside your key’s scope, or the organization has not completed agent verification).

How to fix: Read the fix field, then retry with a key that holds the named permission — created from a credential that already holds it, since a key cannot grant a permission it lacks. Keys created without a permissions object are unrestricted. See missing_permission in the Error Reference.

Test your API key

The fastest way to verify your API key is working is to use the Try it feature in our API Reference.

1. Go to any endpoint in the API Reference
2. Click Try it in the top right of the code panel
3. Enter your API key in the Authorization field
4. Click Send

If you get a 200 response, your key is valid and working. You can then copy the generated code snippet from the panel to use in your application.

Still getting 403?

If none of the above resolves your issue, reach out in our Discord support channel or email support@agentmail.cc with the full error response and the endpoint you are calling.