Introduction
Welcome to the Mailtarget API reference. Follow this guide to get started.
The Mailtarget API is built on HTTP. Our API is RESTful and it:
Utilizes consistent, structured URLs that can be easily predicted.
Leverages the inherent capabilities of HTTP for parameter passing and authentication.
Uses standard HTTP response codes to indicate errors.
Provides responses in the JSON format.
Mailtarget has made available libraries for multiple programming languages. You have the choice to utilize our libraries or opt for your preferred HTTP/REST library compatible with your programming language for initiating HTTP requests to Mailtarget. We encourage you to visit our libraries page where we provide recommendations for HTTP REST libraries.
Endpoints
All calls to the API need to start with the appropriate base URL:
Mailtarget production |
Authentication
Authenticate each request by setting the Authorization header with a valid API key.
We accept the following API key sandbox:
"Authorization": provided in sandbox dashboard
We accept the following API key production:
"Authorization": provide for user production
API conventions
Trailing slashes are ignored: /transmissions is equivalent to /transmissions/.
URL paths, URL query parameter names, and JSON field names are case sensitive.
URL paths are written in lowercase, with dashes separating words.
Query parameters and JSON fields use camel case.
The HTTP status indicates whether an operation failed or succeeded, with extra information included in the HTTP response body.
All APIs return standard HTTP error code formats.
Unexpected query parameters and request body fields are ignored.
Our JSON number type is bounded to a signed 32-bit integer.
Errors
When making an API call, it is possible to receive an error message in response. This error message can indicate either an issue with your request or a problem that occurred on our side. Errors are accompanied by an error code and JSON data that provides a more specific message, description, and API code.
422 Unprocessable Entity
{
"errors": [
{
"message": "required field is missing",
"description": "content object or template_id required",
"code": "1400"
}
]
}
Error table
CODE | STATUS NAME | DESCRIPTION | SUGGESTED ACTION |
400 | Bad Request | There is a problem with your request. | Check your request follows the API documentation and uses correct syntax. |
401 | Unauthorized | You don't have the needed authorization to make the request. | Make sure you are using a valid API key with the necessary permissions for your request. |
403 | Forbidden | The server understood the request but refused to fulfill it. | See if your Mailtarget plan includes the resource you are requesting and your API key has the necessary permissions. |
404 | Not Found | The server couldn't find the requested file. | Change your request URL to match a valid API endpoint. |
405 | Method Not Allowed | The resource does not have the specified method. (e.g. PUT on transmissions) | Change the method to follow the documentation for the resource. |
409 | Conflict | A conflict arose from your request. (e.g. user already exists with that email) | Modify the payload to clear the conflict. |
413 | Request Entity Too Large | The size of the request exceeds the limit. | Check the documented limit for the API and reduce the size of the request. |
415 | Unsupported Media Type | The request is not in a supported format. | Check that your Content-Type header is a supported type and that your request adheres to the documentation. |
420 | Exceed Sending Limit | You exceeded your daily, monthly, or sandbox sending limit. | Check that you are within the limits of your Mailtarget plan. If you are using the sandbox domain, then you'll need to add a sending domain to continue. |
422 | Unprocessable Entity | The request was syntactically correct but failed due to semantic errors. | Make sure that your request includes all of the required fields and your data is valid. |
429 | Too Many Requests | You sent too many requests in a given time period. | Wait 1 to 5 seconds before making another request. Heavier usage patterns may require a more sophisticated and incremental backoff strategy. |
500 | Internal Server Error | Something went wrong on our end. | Try the request again later. If the error does not resolve, check for service updates. You can also contact Support if your issue persists. |
503 | Service Unavailable | We are experiencing higher than normal levels of traffic. | Try the request again later. |