Creating an API key

With an API key an application sends directly through the 2Mail REST API, without an SMTP connection, and gets an identifier back per message to follow its status. You create a separate key per application, so you can revoke them individually.

Step 1: create the key

1. Open the API keys section in the 2Mail dashboard.
2. Create a new key and name it after the application that will use it: the name of your web shop, your CRM, your invoicing package. No generic name like "production" — a year from now nobody remembers what it was for.
3. Attach the key to the sending domain or domains it may send for.
4. Save and copy the key immediately. For security reasons it is shown in full only once; after that you only see the name and the last characters.

Step 2: keep the key safe

Put the key in the secret configuration of your application — an environment variable or a secrets manager — and never in source code, an email or a chat message. Whoever has the key can send on behalf of your domain. Use a separate key for your test and production environments, so a test never reaches your real customers.

Step 3: use the key

Your application sends the key in the authorization header of every request to the API. The documentation of the email API describes the endpoints for sending a message, retrieving its status and managing lists. Every request that sends a message returns an identifier; store it with the message in your own system, so you can later attach the status and bounces to it.

Step 4: test

Send one message to an external test address and check it in the delivery log of the dashboard. The log line shows the name of the key it was sent with — handy for seeing which application sends what.

Revoking or replacing a key

If you suspect a key has leaked, or the developer who knew it leaves, first create a new key, put it in the application, and only then revoke the old one. That way the application never stops. A revoked key stops working immediately; requests using it show up as refused in the log.

Where it goes wrong

• Request refused — the key was copied wrongly, revoked, or not attached to the domain you are sending for.
• Key lost — it cannot be shown again; create a new one.
• One key for everything — works, until you need to switch off a single application. Split them.

If you also want deliveries, bounces and opens back in your application, set up a webhook.

Still stuck?

Give us the name of the key and the time of your request via contact. Never the key itself — we do not need to see it.