A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Mailjet API is how an app or AI agent works with a Mailjet account: sending a transactional email, adding a contact to a list, scheduling a campaign, or reading how many messages were delivered and opened. Access is granted through an API key and its secret, which authenticate every call and carry the full permissions of the account they belong to, with no narrower per-method scopes. Mailjet can also push events to a registered callback when a message it sent is delivered, opened, clicked, or bounces.
How an app or AI agent connects to Mailjet determines what it can reach. There is a route for making calls, a route for receiving delivery and engagement events, and a hosted server that exposes Mailjet to agents, and each is governed by the API key and secret behind it.
The Mailjet API is REST with JSON requests and responses, at https://api.mailjet.com (or https://api.us.mailjet.com for accounts on the US architecture). The v3 management API lives under /v3/REST/ and pages lists with Limit and Offset; the v3.1 Send API lives at /v3.1/send and takes a Messages array. Every call authenticates with the API key and secret over HTTP Basic auth.
Sinch Mailjet publishes an open-source Model Context Protocol server that exposes Mailjet's contacts, campaign, segmentation and statistics APIs to MCP clients like Claude. It runs locally over stdio and is configured with the account's API key and secret. By default it grants read-only access to email data, and write endpoints are enabled by extending the implementation.
Mailjet POSTs JSON to a callback URL when a message it sent is delivered, opened, clicked, bounces, is blocked, is marked as spam, or is unsubscribed; a callback is registered per event type with the eventcallbackurl resource. The Parse API additionally forwards inbound email to a webhook. A receiver returns HTTP 200, and Mailjet retries a failing endpoint every 30 seconds for up to 24 hours.
Every call authenticates with HTTP Basic auth over HTTPS: the API key is the username and the secret key is the password. The same key pair signs both the v3 management API and the v3.1 Send API. The key pair is account-level and carries the full access of the account, with no granular per-endpoint or per-resource scopes, so any restriction has to be enforced in front of the key.
The Mailjet API is split into areas an agent can act on, like sending email, managing contacts and lists, running campaigns, building templates, and reading statistics. Each area has its own methods, and a write in some areas sends real email to real people.
Methods for sending transactional email through the v3.1 Send API and inspecting what was sent.
Methods for creating, reading and updating contacts and their custom properties.
Methods for managing contact lists and the contacts subscribed to them.
Methods for building, scheduling and sending marketing campaigns to a list.
Methods for creating, reading, updating and deleting reusable email templates.
Methods for defining audience segments with filtering expressions.
Methods for reading delivery, open, click and bounce statistics.
Methods for registering callback URLs for delivery events and inbound email parsing.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Send (transactional)Methods for sending transactional email through the v3.1 Send API and inspecting what was sent.4 | ||||||
| POST | /v3.1/send | Send one or more transactional emails through the Send API v3.1, as a Messages array. | write | — | Current | |
Keys are account-level with no per-endpoint scopes. Sends real email; at most 50 messages per call, 50 recipients per message. SandboxMode validates without sending. Acts onmessage Permission (capability)None required VersionIntroduced 2017-08-01 Webhook event sentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/send | Send transactional email through the older v3 Send API, which accepts a single message or up to 100 message objects. | write | — | Current | |
Legacy sending API; v3.1 is preferred for new integrations and gives per-message error reporting. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event sentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/message/{id} | Retrieve the details and status of a message that was sent. | read | — | Current | |
Read-only. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/messagehistory/{id} | Retrieve the event history (sent, opened, clicked) for a single message. | read | — | Current | |
Read-only. Acts onmessagehistory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContactsMethods for creating, reading and updating contacts and their custom properties.7 | ||||||
| GET | /v3/REST/contact | List contacts on the account (paged with Limit and Offset). | read | — | Current | |
Read-only; returns email addresses and contact metadata. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/contact | Create a contact from an email address (and optional name). | write | — | Current | |
A core write; adds a person to the account's contact base. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/contact/{id} | Retrieve a single contact by id or email address. | read | — | Current | |
Read-only. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/REST/contact/{id} | Update a contact's name or exclusion (unsubscribe) status. | write | — | Current | |
A core write. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/contact/managemanycontacts | Add or update many contacts in one background job, optionally subscribing them to lists. | write | — | Current | |
Bulk write; runs as a job whose status is polled with a GET on the same path. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/REST/contactdata/{id} | Set the custom property values (contact data) for a contact. | write | — | Current | |
Writes the values of custom contact properties. Acts oncontactdata Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/contactmetadata | Define a custom contact property (its name and data type). | write | — | Current | |
Defines an account-wide custom property usable on every contact. Acts oncontactmetadata Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contact listsMethods for managing contact lists and the contacts subscribed to them.6 | ||||||
| GET | /v3/REST/contactslist | List the account's contact lists. | read | — | Current | |
Read-only. Acts oncontactslist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/contactslist | Create a contact list. | write | — | Current | |
A core write. Acts oncontactslist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/REST/contactslist/{id} | Update a contact list's name or properties. | write | — | Current | |
A core write. Acts oncontactslist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/REST/contactslist/{id} | Delete a contact list. | write | — | Current | |
Removes the list; the contacts themselves remain on the account. Acts oncontactslist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/contactslist/{id}/managemanycontacts | Subscribe, unsubscribe or remove many contacts on a specific list in one background job. | write | — | Current | |
Bulk write; runs as a job whose status is polled with a GET on the same path. Acts oncontactslist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/contact/{id}/managecontactslists | Manage one contact's subscription across several lists in a single call. | write | — | Current | |
Adds, removes or unsubscribes one contact across multiple lists. Acts oncontactslist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Campaigns & newslettersMethods for building, scheduling and sending marketing campaigns to a list.6 | ||||||
| POST | /v3/REST/campaigndraft | Create a campaign (newsletter) draft with a sender, subject, locale and target list. | write | — | Current | |
Creates a draft; nothing is sent until the send or schedule call. Acts oncampaigndraft Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/campaigndraft/{id}/detailcontent | Add the HTML and text body to a campaign draft. | write | — | Current | |
Sets the content of an existing draft. Acts oncampaigndraft Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/campaigndraft/{id}/test | Send a test copy of a campaign draft to named recipients. | write | — | Current | |
Sends real email, but only to the test recipients, not the list. Acts oncampaigndraft Permission (capability)None required VersionAvailable since the API’s base version Webhook event sentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/campaigndraft/{id}/schedule | Schedule a campaign draft to send at a future date (ISO 8601). | write | — | Current | |
Queues a send to the whole target list; a DELETE on the same path cancels it. Acts oncampaigndraft Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/campaigndraft/{id}/send | Send a campaign draft to its target list immediately. | write | — | Current | |
Delivers the campaign to a whole list of real people at once. Acts oncampaigndraft Permission (capability)None required VersionAvailable since the API’s base version Webhook event sentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/campaign | List sent and in-progress campaigns on the account. | read | — | Current | |
Read-only. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TemplatesMethods for creating, reading, updating and deleting reusable email templates.4 | ||||||
| GET | /v3/REST/template | List the account's email templates. | read | — | Current | |
Read-only. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/template | Create an email template. | write | — | Current | |
A core write. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/template/{id}/detailcontent | Add or replace a template's HTML and text content. | write | — | Current | |
Setting only one of HTML or text clears the other; PUT preserves unspecified fields. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/REST/template/{id} | Delete an email template. | write | — | Current | |
Irreversible; a live send referencing the template will fail. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SegmentsMethods for defining audience segments with filtering expressions.2 | ||||||
| POST | /v3/REST/contactfilter | Create a segment (contact filter) from a filtering expression to target a campaign. | write | — | Current | |
Defines who a campaign reaches; assigned to a campaign draft via SegmentationID. Acts oncontactfilter Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/contactfilter | List the account's segments (contact filters). | read | — | Current | |
Read-only. Acts oncontactfilter Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StatisticsMethods for reading delivery, open, click and bounce statistics.3 | ||||||
| GET | /v3/REST/statcounters | Retrieve key performance statistics (delivery, open, click rates) by source and timeframe. | read | — | Current | |
Read-only. Acts onstatcounters Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/contactstatistics | Retrieve per-contact engagement counts (delivered, opened, clicked, blocked). | read | — | Current | |
Read-only. Acts oncontactstatistics Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/REST/bouncestatistics | Retrieve bounce details, including timestamp and whether the bounce is permanent. | read | — | Current | |
Read-only. Acts onbouncestatistics Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Event & Parse webhooksMethods for registering callback URLs for delivery events and inbound email parsing.5 | ||||||
| GET | /v3/REST/eventcallbackurl | List the registered event callback URLs (webhook endpoints) per event type. | read | — | Current | |
Read-only. Acts oneventcallbackurl Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/eventcallbackurl | Register a callback URL for an event type (open, click, bounce, spam, sent, unsub, blocked). | write | — | Current | |
Controls where Mailjet pushes event data; takes EventType, Url and Version. Acts oneventcallbackurl Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/REST/eventcallbackurl/{id} | Remove a registered event callback URL. | write | — | Current | |
Stops Mailjet pushing that event type to the URL. Acts oneventcallbackurl Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/REST/parseroute | Create an inbound parse route that delivers parsed incoming email to a webhook. | write | — | Current | |
Routes inbound email to a webhook; available on paid plans only. Acts onparseroute Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/REST/parseroute/{id} | Delete an inbound parse route. | write | — | Current | |
Stops inbound email being parsed and forwarded. Acts onparseroute Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mailjet can notify an app when something happens to a message it sent, like the message being delivered, opened, clicked, bouncing, or marked as spam. It POSTs a JSON event to a callback URL registered per event type, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
sent | The destination mail server accepted the message. This is the delivery confirmation. | /v3.1/send/v3/send/v3/REST/campaigndraft/{id}/send/v3/REST/campaigndraft/{id}/test |
open | A recipient opened the message, recorded with IP address and approximate location. | /v3.1/send/v3/REST/campaigndraft/{id}/send |
click | A recipient clicked a tracked link in the message, recording the URL. | /v3.1/send/v3/REST/campaigndraft/{id}/send |
bounce | The message could not be delivered, with a flag for whether the bounce is permanent (hard) or temporary (soft). | /v3.1/send/v3/REST/campaigndraft/{id}/send |
blocked | The message was blocked before SMTP transmission, for example because the recipient is on the exclusion list. | /v3.1/send/v3/REST/campaigndraft/{id}/send |
spam | A feedback-loop program reported the message as spam after the recipient marked it. | /v3.1/send/v3/REST/campaigndraft/{id}/send |
unsub | A recipient unsubscribed, recorded with the list and tracking details. | /v3.1/send/v3/REST/campaigndraft/{id}/send |
Mailjet limits how fast an app can call the API and how much it can send, by a per-account request rate and by separate send caps that depend on the plan.
Mailjet meters API requests per account, not by a per-method cost. Going over the request rate returns HTTP 429 with the Mailjet error MJ-002, 'Exceeded API Rate Limit'. Sending is capped separately by plan and account standing rather than by the API rate: a free account is limited to 200 emails per day, and a key in test mode is limited to 10 emails per hour. A single v3.1 Send call accepts at most 50 messages, and a single message at most 50 recipients across To, Cc and Bcc.
A v3 list endpoint pages with Limit and Offset. Limit sets the page size, defaulting to 10 with a maximum of 1000; Offset is the index of the first object to return, so Offset=100 with Limit=100 returns objects 101 to 200. A Sort parameter orders results by a property, ascending by default. The response carries Count for the page, Total for the full match, and the rows in Data.
A v3 list returns at most 1000 objects per page. A single Send API v3.1 call carries at most 50 messages, each with at most 50 recipients across the To, Cc and Bcc fields, so larger sends are split across multiple calls. Inbound email handled by the Parse API delivers attachments Base64-encoded in the webhook payload.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed: invalid JSON, a missing mandatory property, or an invalid value. | Read the ErrorMessage, fix the request body or parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid authorization was provided; the API key and secret pair is missing or wrong. | Confirm the API key is the username and the secret key the password in HTTP Basic auth, and rotate the pair if it leaked. |
| 403 | Forbidden | The credentials are valid but do not have access to the requested resource. | Check the account behind the key has access to the resource, and that the resource id belongs to that account. |
| 404 | Not Found | The requested object or path does not exist on the account. | Verify the resource path and object id. |
| 429 | MJ-002 (rate limit) | The API rate limit was exceeded, returned as 'Exceeded API Rate Limit'. | Back off and retry with exponential backoff, and smooth the request rate. |
| 500 | Internal Server Error | An error on Mailjet's side. The body carries an ErrorIdentifier referencing Mailjet's internal log. | Retry with backoff, and give the ErrorIdentifier to Mailjet support if it persists. |
Mailjet runs two API generations side by side: the v3 management API for contacts, campaigns, templates and statistics, and the v3.1 Send API for transactional email, which v3 sending predates.
Mailjet runs two API generations together. The v3 management API covers contacts, lists, campaigns, templates, segments and statistics under /v3/REST/. The v3.1 Send API at /v3.1/send is the current way to send transactional email, released in August 2017 with per-message error reporting; it is not backward-compatible with v3 sending, which Mailjet still supports.
Send API v3.1 launched in August 2017 with a Messages array payload, per-message status and error reporting, and a 50-message-per-call cap. It is not backward-compatible with the v3 Send API, which remains supported for higher per-call message counts.
Use v3.1 for sending and v3 for everything else; both are supported.
Mailjet API versioning ↗Bollard AI sits between a team's AI agents and Mailjet. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.