REST API: Your First Request in Ten Minutes

Your first request to a sending REST API takes less time than setting up a mail client. Seriously. You need a key, a verified domain and one command in the terminal. The goal of this text is narrow: get you to one working call that ends with an email in the inbox. Full integration, webhooks and list hygiene come later. First you have to see a 202 code and the message you sent yourself.

Why you need a REST API for sending mail

For a newsletter the panel is enough. You paste the content, pick a segment, schedule the send and you are done. The API starts to matter when a message has to go out a second after an event in your system, and nobody is sitting at a browser.

Use cases? Predictable ones: order confirmation, password reset, a notification from a mobile app, syncing a recipient list with a CRM database. The common denominator is an event in code that has to pull an email behind it immediately. If your system already has a ready connector, check the list of available integrations first – part of the work may already be done for you.

Technically there is no magic here. A REST API is plain HTTP: a resource address, a method, headers, JSON in the body and a response code. That is all you need to know at the start. The rest is the detail of a specific set of documentation, which you learn on your second and third call.

Let us separate two paths right away. Leave SMTP to applications that cannot do anything else – old ERP systems, plugins, network printers. The API gives you something SMTP will not give you comfortably: a message identifier and a status you can query later to find out what happened to the message. With SMTP you get a server response and hope. With an API you get an object you can come back to.

What you need before the first request

The list is short and there is nothing exotic on it:

• An API key generated in the panel, ideally a separate one for the test environment.
• A verified sender domain with SPF and DKIM in place.
• A From address on that exact domain, not on Gmail and not on the client’s domain.
• A terminal with curl or any HTTP client: Postman, Insomnia, the client built into your IDE.

Keep the key in an environment variable or in a secrets manager. Never in the repository, never in frontend code. A key in browser JavaScript means every visitor to your site can send mail from your domain. We have seen such slips and they end with weeks of cleaning up reputation.

Set the DNS records before you send anything. Without SPF and DKIM the test message will land in spam and distort the whole picture – you will start looking for a bug in the code while the problem sits in the DNS zone. Return-Path and PTR are the job of the sending infrastructure, in our case our own fleet of servers. You do not have to configure them, but it is good to know that someone keeps them and that they affect whether filters trust you. If you send in larger volumes, it is worth reading up on the authentication requirements Gmail and Yahoo set for bulk senders before the first campaign.

Tip: set up your first test address on a mailbox where you have full administrative access. You have to be able to look at the raw message headers, because that is where the authentication result shows up.

Anatomy of a request: authentication, endpoint, payload

Authentication goes in the Authorization header with a Bearer token. The key belongs in the header, never in the query string. The query ends up in proxy logs, in browser history and in monitoring systems, so a secret in a URL is a secret exposed.

Headers you cannot do without

The second mandatory header is Content-Type: application/json plus actually valid JSON in the body. A missing header or a typo in its value is the most common cause of a 415 response. Check your commas and quotation marks too – JSON does not forgive, and the error message can be terse.

Method and body content

You send with a POST to the message resource, because you are creating a new object. GET is for querying the status of a message that already exists. Ordinary REST semantics, the same as in any other API.

A minimal payload has four fields: sender, recipient, subject and content in HTML or plain text. The rest is optional – copies, attachments, tags, custom headers, scheduled send time. Do not add them on the first attempt. Every extra field is another place for a validation error.

For repeated requests, the industry standard is an idempotency key sent in a header. Thanks to it, a retry after a timeout will not send the mail a second time. Implement it from the start, because adding it later means rewriting the error handling layer.

The first request step by step

1. Generate an API key in the panel and store it in an environment variable.
2. Check the DNS records of the sender domain: SPF, DKIM, and eventually DMARC too.
3. Put together a minimal JSON with sender, recipient, subject and content.
4. Send a POST with curl, with the Authorization and Content-Type headers.
5. Read the response code and the body of the returned object.
6. Open the mailbox and look at the message together with its headers.

A curl call has a fixed structure regardless of the provider: curl -X POST, the message resource address, -H “Authorization: Bearer $API_KEY”, -H “Content-Type: application/json” and -d with your JSON. You take the exact endpoint address from your provider’s documentation, because this part differs everywhere.

A 2xx response contains the message identifier. Save it right away, ideally in the application log next to the order or user identifier. You use that identifier later to query delivery, opens and bounces. Without it you have an email you cannot find in the statistics.

Tip: send the first request to yourself, the second to a mailbox on a completely different domain and a different provider. Only a comparison of two recipients shows whether authentication actually works, or whether your own server is simply being lenient with you.

Response codes and the errors you will see first

Codes 401 and 403 mean a problem with the key. Usually a key from a different environment, a key copied with a trailing space, or a key without permission for that specific resource. Check this before you start digging in the payload.

A 422 with syntactically correct JSON is content validation. Most often a sender outside the verified domain, an empty subject or a recipient address in the wrong format. The returned message usually points at the field, so read the response body, not just the status.

A 429 is the request limit. Handle the header with the wait time and apply exponential backoff. A loop that retries the request without a break only deepens the problem and is sometimes treated as abuse. While you are at it, it is worth checking the sending limits in the individual plans, because some 429 problems are simply a package that is too tight.

5xx errors are on the API side. That is a signal to retry with an idempotency key, not to modify the payload. Changing the content on a server error is a typical mistake that later generates duplicates.

And one thing more important than the rest: a 2xx code means accepted for sending, not delivered. The message is sitting in a queue. Whether it arrived you will only learn from a callback event.

From one request to production: what to do next

Webhooks are the next step, not an option. Hook up events for delivery, open, click, hard and soft bounce, and complaints. Without them you have no picture of deliverability at all – you only see that your code called the API.

Remove hard bounces and complaints from the list automatically, in the same transaction in which you receive them. Manual cleaning always drifts out of sync, and every further send to a dead address cuts into sender reputation. You can catch part of the problem earlier, at the point of collecting addresses, by checking whether an address exists without sending anything to it.

Separate transactional traffic from marketing traffic, ideally onto separate domains or subdomains. A campaign with a high complaint rate must not drag password resets down with it – these are messages of a completely different weight for the user. If you are looking for a place where both types of traffic are handled on an own fleet of servers, take a look at the MailCraft email marketing platform.

A new domain needs a warmup. Growing volume over several weeks, watching how the large filters behave, reacting to the first drop instead of waiting. Getting out of a block takes longer than avoiding one.

Honestly about the limits: some things from our roadmap are not yet available in the panel. We describe them here as industry practice, because that is how it is solved, not as a ready feature to click.

Consent and law: this is not a separate stage

GDPR and article 398 of the Polish electronic communications law, PKE, apply in B2B as well. A company address is not an exception if it leads to a specific person. The assumption that you can write to companies without consent is an expensive mistake.

Record proof of consent: timestamp, IP address, source of the sign-up and the wording of the clause as it stood on the day it was given. A later change to the terms does not invalidate old consent, but you have to be able to show what exactly someone agreed to.

Transactional and marketing messages rest on different legal grounds. Do not glue an offer onto an order confirmation – one promotional sentence changes the classification of the whole message.

Unsubscribing has to work through the API just as fast as in the panel. No delay, no extra steps for the recipient, no logging in. A difficult unsubscribe ends with a click on the report spam button, and that hurts more than losing the address.

Compliance translates directly into deliverability. A clean list with consent generates fewer complaints, and fewer complaints mean better sender reputation with the large filters.

Summary: ten minutes is only the beginning

The first request really does take a few minutes. The rest of the work is error handling, webhooks and list hygiene – and that is where most of the integration time goes.

The order that works: DNS first, then one email to yourself, then handling response codes, then webhooks, and volume only at the end. Reversing that order ends with a block on the first larger send.

Without SPF, DKIM and a reaction to bounces, even a technically correct request will not give you deliverability. The API delivers the message to the queue; the rest is handled by domain authentication and list quality.

If your integration is unusual – your own queueing system, high volume peaks, migration from another platform – write to our team. We will go through it together, without rushing and without artificial deadlines.