Skip to content
This repository has been archived by the owner on May 24, 2019. It is now read-only.

Latest commit

 

History

History
206 lines (146 loc) · 12.1 KB

_getting-started.md

File metadata and controls

206 lines (146 loc) · 12.1 KB

#Getting Started

This is a quick tutorial to get you started using our API.

We will show you how to send your first email, how to authenticate with our API and tell you more about Mailjet RESTful API.

We will also show you how to verify your domain to get a better deliverability of your emails.

Make your first request

Give it a go and send your first email...

This simple example shows how to send an email with the API in a few easy steps.

First, you need to have at least one active sender address in the Mailjet system. Visit the Sender domains & addresses section to check and setup your domain and sender.

Second, you need to find your credentials, the API Key and the API Private Key, in the account/API Keys section.

Example available only with CURL

curl -s \
	-X POST \
	--user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
	https://api.mailjet.com/v3/send \
	-H "Content-Type: application/json" \
	-d '{
		"FromEmail":"$SENDER_EMAIL",
		"FromName":"Me",
		"Recipients": [ 
			{
			"Email":"$RECIPIENT_EMAIL"
			}
		],
		"Subject":"My first Mailjet Email!",
		"Text-part":"Greetings from Mailjet."
	}'

Now run the Curl command line, after replacing:

  • $MJ_APIKEY_PUBLIC : your API Key
  • $MJ_APIKEY_PRIVATE : your API Private Key
  • $SENDER_EMAIL : sender email address found in the interface
  • $RECIPIENT_EMAIL : the recipient email address of your test

About the Mailjet RESTful API

###API in a Nutshell

The Mailjet API is designed to be RESTful compliant. This means that the API communicate over HTTP (including the use of HTTP verbs) . The API allows you to create, read, update and delete (CRUD) resources. Also, each single resource has a URI (Unique Resource Identifier) to help access it's properties.

The CRUD methods on the Mailjet API correspond to HTTP's verbs POST, GET, PUT and DELETE, so that depending on the resources and providing you have the access rights, you can do the following :

  • GET /$resource gives you a list of resources of type $resource
  • GET /$resource/$id gives you a single resource of type $resource, identified by the id $id, using its URI
  • POST /$resource allows you to create a resource of type $resource
  • PUT /$resource/$id allows you to update an existing resource of type $resource, identified by the id $id, using its URI
  • DELETE /$resource/$id allows you to delete a single resource of type $resource, identified by the id $id, using its URI

Each resource has a list of properties and methods you can see in our API reference.

On the Mailjet API, all PUT method use will behave like a PATCH method. The update will affect only the specified properties, the other properties of an existing single resource will not be modified nor deleted. It also mean that all non mandatory properties can be omitted from your payload.

###Authenticate

In order to use the Mailjet API you have to authenticate using HTTP Basic Auth. HTTP Basic Auth requires you to provide a username and a password for each API request. The username is your API Key and the password is your API Secret Key, which are both generated for you after registration.

TIP: You can find the API Key and the API Private Key in the API keys Management section. 
#To make better use of our cURL examples you can set your keys in your environment variables with the following commands: 
export MJ_APIKEY_PUBLIC=xxxxxxxxxxxxxxxxxxxxxx
export MJ_APIKEY_PRIVATE=xxxxxxxxxxxxxxxxxxxxxxx

#View user information : now, you don't need to replace $MJ_APIKEY_PUBLIC and $MJ_APIKEY_PRIVATE when running a cURL command
curl --user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" https://api.mailjet.com/v3/REST/user

The server should respond with the following data:

{
	"Count": 1,
	"Data": [
		{
			"ACL": "",
			"CreatedAt": "",
			"Email": "miss@mailjet.com",
			"ID": "",
			"LastIp": "",
			"LastLoginAt": "",
			"Locale": "",
			"MaxAllowedAPIKeys": "5",
			"Timezone": "",
			"Username": "",
			"WarnedRatelimitAt": ""
		}
	],
	"Total": 1
}

Most developers use one of our API libraries for their production systems and the respective library documentation tells you where to place your API Keys. However for testing purposes it can be nice to query the API directly from the shell.

In this example :

  • $MJ_APIKEY_PUBLIC is your API Key
  • $MJ_APIKEY_PRIVATE is your API Private Key

Both these keys can be found in your control panel, once you're logged-in and your account is provisioned (activated).

The usual json payload response will have the following structure : {"Count": int, "Data": array, "Total": int} where Count and Total represent the number of line affected by your API call. When using the countOnly filter Total will be the global number of elements corresponding to your API call.

###Status Codes

These status codes will be sent back by the API to notify of the success or failure of your calls.

Code Description
200 OK All went well. Congrats!
201 Created The POST request was successfully executed.
204 No Content No content found or expected to return. Returned when DELETE was successful.
304 Not Modified The PUT request didn't affect any record.
400 Bad Request One or more parameters are missing or maybe mispelled (unknown resource or action)
401 Unauthorized You have specified an incorrect Api Key / API Secret Key. You may be unauthorized to access the API or your API key may be expired. Visit API keys Management section to check your keys.
403 Forbidden You are not authorised to access this resource.
404 Not Found The resource with the specified ID you are trying to reach does not exist.
405 Method Not Allowed The method requested on the resource does not exist.
500 Internal Server Error Ouch! Something went wrong on our side and we apologize! Please contact our support team who'll be able to help you on this
```json { "ErrorInfo": "Bad Request", "ErrorMessage": "Unknown resource: \"contacts\"", "StatusCode": 400 } ```

In addition to the status codes, in case of error, you can find hints in a standardised JSON response with the reason under ErrorMessage.

##Verify Your Domain

We strongly recommend that you verify the domain or subdomain you will use for sending emails. To do so you have to go to your account settings and add the domain you want to use for sending emails. Once the domain is successfully set up we generate an SPF and a DKIM record for you.

SPF is a DNS TXT record and acts as a filter. It is used to specify a whitelist of IP addresses. This whitelist can be queried by mail clients to see whether a sender IP is in the list.

DKIM is another DNS TXT record and contains a public key. We automatically generate a public/private key pair for you after registration. The private key is used to sign every message you send. Email clients can then check your DKIM record and use it to verify the signature. Together, SPF and DKIM form the technical basis of email deliverability.

Tip: You can find both records together with instructions in your account settings. Go to your account setup page and click on the info button for your domain.

Once your domain is verified you should add the SPF and DKIM records to your domain using the domain configuration tool of your DNS Provider.

You can refer to our step-by-step user guides on creating DNS records:

You can also visit the offical and third-party documentations for DNS providers :

With some DNS providers the setup can be quite tedious, but we would be happy to help you out. Just contact our support!

Where to go from here ?

In the next sections of this guide, you will find 2 common user cases:

You can also discover our real time notification API that allows you to monitor every events (sent, opened, clicked, bounced...) on the emails you will send.

Mailjet also offers an inbound emails parsing solution that allows to easily manage your contacts replies.

The examples in this documentation are using Mailjet libraries. Find the list and where to download them here