Sending keys

A sending key is a sending identity in EmailMassivo: one verified domain plus a sending history. Every transactional email goes out through a specific key. In POST /api/v1/public/emails its id is passed in the keyId field; if the field is omitted, the default key of the sender's domain is used.

The sending key model

Each key has a set of attributes that matter to an integrator:

• id — a numeric identifier: keyId in the request body and in the sending history filters.
• Domain — exactly one of your domains, through which emails from this key are sent — see Domain and from.email.
• Status — enabled, disabled, or banned. You can only send through enabled; with the other statuses sending returns 422 SENDING_KEY_NOT_ACTIVE. A new key is created in the disabled status and becomes enabled after EmailMassivo moderation.
• isDefault — whether the key is the default key of its domain.
• Name — for your convenience; it doesn't affect the API.

Only keys for sending through the API work for HTTP sending. An SMTP key in keyId returns 404 SENDING_KEY_NOT_FOUND, like a nonexistent key: use it only for SMTP.

One account can have several sending keys — for example, for different domains or different products. A single token with the email.send scope sends through any key of the account; you don't need a separate token per key.

Finding a sending key's id

List your keys through the API (sending_keys.read scope):

curl https://api.emailmassivo.com/api/v1/public/sending-keys \
  -H "Authorization: Bearer $API_TOKEN"

The response is an array of keys with id, name, status, isThrottled, isDefault, and the attached domain. See List sending keys.

The id is also shown in the dashboard: Transactional sends section → "Connected sending keys" block — each key card has an "ID …" badge next to its status.

Default key

If keyId isn't passed to POST /api/v1/public/emails, the email goes through the default key of the from.email domain. Your integration doesn't need to store a key id: the sender address is enough.

• Each domain has at most one default key. Only a key for sending through the API can be one. SMTP keys aren't shown in the public API and are never default keys.
• To find the default key, look for isDefault: true in the key list and in a key by id. In the dashboard such a key has a "Default" badge.

How a key becomes the default

• A new key becomes the default key if its domain doesn't have one yet. Keys are created in the disabled status, so until moderation, sending through a new default key returns 422 SENDING_KEY_NOT_ACTIVE.
• Another key of the same domain doesn't become the default key by itself: to send through it without keyId, change the default key.

How to change the default key

Through the API — PATCH /api/v1/public/sending-keys/{keyId} with isDefault: true, sending_keys.write scope:

curl -X PATCH https://api.emailmassivo.com/api/v1/public/sending-keys/42 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"isDefault": true}}'

The domain's previous default key stops being the default. Pass only isDefault: true: to clear the flag from a key, make another key the default. Over MCP — the public_sending_keys_update tool with the same field.

In the dashboard — the key card menu → "Make default key" and confirm. The default key is marked with a "Default" badge on its card.

When the default key is unavailable

• The default key is disabled or banned — 422 SENDING_KEY_NOT_ACTIVE. Set another default key or pass keyId.
• The default key is deleted — sending from this domain without keyId returns 422 SENDING_KEY_DEFAULT_NOT_CONFIGURED until you set another key.

Traffic quality control

If we notice bad traffic going through a key — a high rate of complaints or bounces from recipients — we first throttle sending from that key, and if the metrics keep getting worse, we ban the key. To restore a banned key, contact EmailMassivo support.

To keep your key from getting banned:

• Set up email webhooks and handle email.unsubscribed, email.complained, and email.bounced with bounceType: permanent.
• Remove such recipients from your base promptly.
• Don't send to "cold" lists — they produce a high complaint rate.

How to tell that a key is throttled

Check the isThrottled field in the List sending keys response. Sending itself still returns a normal success response while throttled — throttling shows up as a longer delay between accepting the email and delivering it.

Quota and rate

Quota is the number of emails per month, shared by all keys of the account:

• The quota value is set by your subscription plan.
• All sending keys of the account draw from one quota.
• The quota renews at the start of each billing period; leftovers don't roll over.

How the quota is charged and what to do when it isn't enough (402 PAYMENT_REQUIRED, the X-Quota-Remaining header) is covered in Idempotency and quota. You change your plan in the dashboard.

Sending rate. The request limit per API key and the email limit per sender domain are in Rate limit.

Domain and from.email

Each key is bound to one of your domains, and from.email must be in this key's domain:

• from.email not in the key's domain — 422 SENDER_DOMAIN_MISMATCH; the key's domain not verified — 422 SENDING_KEY_DOMAIN_NOT_VERIFIED.
• To send from another domain, create a key in it. Without keyId, the email goes through the default key of the from.email domain automatically.
• DKIM, SPF, and DMARC are configured per domain in the dashboard: Senders → Domains tab (record statuses and the "Check" button are there too).
• If domain verification "breaks" (the DNS records stop passing the check), the dashboard warns you on the key page; if you don't restore the records within 72 hours, the key is deactivated.

What's available through the API

You can manage keys through the public API:

• List sending keys, a key by id, and key statistics for a period — id, name, status, isThrottled, isDefault, attached domain (sending_keys.read scope).
• Create, update — name and isDefault, delete a key (sending_keys.write scope). A key can only be created for a verified domain, in the disabled status.
• Sending history — the key's deliveries and emails (email.read scope).
• List domains — verification status and DNS records.

Dashboard only: change your subscription plan.

Handling common errors

Key and domain errors of POST /api/v1/public/emails. The full list is in Send error codes.

HTTP	error.code	Cause	Action
402	PAYMENT_REQUIRED	Not enough email quota	Wait for the next billing period to start or change your plan
404	SENDING_KEY_NOT_FOUND	No key with this keyId in the account, it was deleted, or it's an SMTP key	Check keyId; for HTTP sending, use a key for sending through the API
404	SENDING_KEY_DOMAIN_NOT_FOUND	The from.email domain isn't in the account	Fix from.email or add the domain
409	SENDER_DOMAIN_BLOCKED	The domain is blocked	Contact support
422	SENDING_KEY_NOT_ACTIVE	The key — explicit or default — isn't in the enabled status	Check the key status; for a new key, wait for moderation; if banned for traffic, contact support
422	SENDING_KEY_DEFAULT_NOT_CONFIGURED	The domain has no default key	Pass keyId or set a default key
422	SENDING_KEY_DOMAIN_NOT_VERIFIED	The key's domain isn't verified	Restore the DNS records and re-check the domain
422	SENDER_DOMAIN_MISMATCH	from.email isn't in the key's domain	Send from an address in the key's domain or don't pass keyId

After you fix the key or the domain, retry the request with a new Idempotency-Key — see Which responses are stored.

See also

• Send a transactional email — the POST /api/v1/public/emails request.
• Send error codes.
• Migrating to the Email API.