# Mailjet API Reference

The Mailjet API is organized around [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer) principles. It features predictable, resource-oriented URLs, accepts and returns JSON-encoded bodies, and uses standard HTTP response codes, authentication, and verbs.

Mailjet exposes two complementary APIs:

|  | Email API | Content API |
|  --- | --- | --- |
| **Base path** | `/v3` | `/v1` |
| **Purpose** | Send emails, manage contacts, track statistics, configure webhooks | Manage email templates, template content, images, labels, and tokens |
| **Authentication** | HTTP Basic Auth | HTTP Basic Auth or Bearer Token |
| **Reference** | [Email API Reference](/openapi/openapi-mailjet) | [Content API Reference](/openapi/openapi-passport) |


## Base URL

All API requests use a single base URL:

```
https://api.mailjet.com
```

## Authentication

All API requests require authentication over HTTPS.

**HTTP Basic Auth** — used by both APIs. Your API Key is the username and your Secret Key is the password. Find them in the [API Key Management page](https://app.mailjet.com/account/apikeys).

**Bearer Token** — available for the Content API only. Tokens are created via `POST /v1/REST/tokens` and carry granular permissions. See [Token Management](/openapi/openapi-passport/tokens/post_v1_tokens).

## Email API (`/v3`)

The Email API covers everything related to sending and tracking emails:

- **Send Email** — Send transactional or marketing emails via [Send API v3.1](/openapi/openapi-mailjet/send-emails/postsendv31) (detailed feedback, up to 50 messages) or [Send API v3](/openapi/openapi-mailjet/send-emails/postsendv3) (higher throughput, up to 100 messages).
- **Contacts & Lists** — Create and manage contacts, contact lists, subscriptions, and contact metadata.
- **Campaigns** — Create campaign drafts, schedule sends, and manage A/X testing.
- **Templates** — Manage legacy v3 email templates and presets.
- **Statistics** — Retrieve delivery, open, click, bounce, and geographic statistics.
- **Webhooks** — Track delivery and engagement events via callback URLs.
- **Messages** — Query message history, delivery status, and per-message details.
- **Senders & Domains** — Register sender addresses, validate domains (SPF/DKIM).
- **Parse API** — Process inbound emails and forward parsed content to your webhook.


PUT = PATCH
In the Mailjet API, all `PUT` requests behave like `PATCH` — only the specified properties are updated. Omitted properties are left unchanged.

## Content API (`/v1`)

The Content API manages everything related to email content and assets:

- **Templates** — [Create](/openapi/openapi-passport/templates/post_v1_templates), [list](/openapi/openapi-passport/templates/get_v1_templates), [update](/openapi/openapi-passport/templates/put_v1_template), and [delete](/openapi/openapi-passport/templates/delete_v1_template) email templates with support for HTML (Edit Mode 2) and MJML (Edit Mode 4).
- **Template Contents** — Manage the content lifecycle: [create drafts](/openapi/openapi-passport/template-contents/post_v1_template_contents), [update](/openapi/openapi-passport/template-contents/put_v1_template_content_by_type), [publish](/openapi/openapi-passport/template-contents/post_v1_template_contents_publish), [lock/unlock](/openapi/openapi-passport/template-contents/post_v1_template_contents_lock). Up to 5 versions per status are stored.
- **Images** — [Upload images](/openapi/openapi-passport/images/post_v1_data_images) (max 2MB), manage [thumbnails](/openapi/openapi-passport/images/put_v1_data_images_content), and [retrieve URLs](/openapi/openapi-passport/images/get_v1_images) for use in templates.
- **Labels** — [Create](/openapi/openapi-passport/labels/post_v1_labels) and manage labels to categorize templates and images.
- **Tokens** — [Generate Bearer Tokens](/openapi/openapi-passport/tokens/post_v1_tokens) with fine-grained permissions for template, image, and label management.


## Pagination & Sorting

Both APIs support pagination via query parameters:

| Parameter | Type | Description |
|  --- | --- | --- |
| `Limit` | integer | Number of results per page. Default: 10, max: 1000. |
| `Offset` | integer | Index of the first object to return. |
| `Sort` | string | Sort by a property. Example: `Sort=Name+DESC`. |


## HTTP Status Codes

| Code | Meaning |
|  --- | --- |
| `200` | Success |
| `201` | Resource created |
| `204` | Success, no content returned |
| `400` | Bad request — missing or invalid parameters |
| `401` | Unauthorized — invalid API key or secret |
| `403` | Forbidden — insufficient permissions |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Internal server error |


## Official SDKs

Mailjet provides official wrappers for popular languages:

[PHP](https://github.com/mailjet/mailjet-apiv3-php) · [Python](https://github.com/mailjet/mailjet-apiv3-python) · [Ruby](https://github.com/mailjet/mailjet-gem) · [Java](https://github.com/mailjet/mailjet-apiv3-java) · [Node.js](https://github.com/mailjet/mailjet-apiv3-nodejs) · [Go](https://github.com/mailjet/mailjet-apiv3-go) · [C#](https://github.com/mailjet/mailjet-apiv3-dotnet)