Open an email inbox and return its address. Use this when you need an address to sign up for a service or to receive a one-time code.

The address is permanent and stays until you delete it, so a test suite can reuse one address across runs instead of opening a new inbox each time. Only the messages inside expire, on the retention window you choose.

label needs a paid plan; on free it is reported back in ignored_fields. retention_hours is optional (0 = your plan's max); requests above your plan are capped.

List all inboxes available to this API key.

Read messages in the given inbox address (newest first).

direction is "in" for received mail (default), "out" for mail sent from this address, or "all" for both. Received mail is the default so that a reply you are waiting for is not confused with a message you just sent.

Poll the inbox until an OTP code arrives (or timeout). Returns {otp_code, email}.

Poll the inbox until a new message ARRIVES (or timeout). Returns {email}.

Only received mail counts, so you can send to a peer and then wait for their reply without matching your own outgoing message.

Send an email FROM the given inbox address (DKIM-signed via MailFlat's MTA). Use for replies or outbound automation. html is optional.

Returns once the mail is ACCEPTED for delivery, not once it is delivered: delivery runs on a queue and the result arrives via webhook or by reading the message back.

cc addresses appear in the mail's headers; bcc addresses never do — not even in their own copy. Attachments are not available here; send those from the SDK.

Reply to a message so it stays in the SAME conversation.

Prefer this over send_email when answering: it fills in the recipient, an Re: subject and the threading headers. A plain send_email starts a new conversation in the recipient's client, which does not look like a reply.

Find out whether a mail you sent was actually delivered.

send_email only means "accepted for delivery"; the mail goes out later on a queue. Call this with the message_id send_email returned to learn the outcome.

Returns delivered: true once it went out. If it is still queued when the timeout elapses you get timed_out: true with delivered: false — that is NOT a failure and you must NOT send the mail again; the queue is still retrying. status tells you whether it has been attempted yet (queued) or attempted and rescheduled (retrying), and error carries what the last attempt reported. Permanent failure comes back the same way, as status: failed with the reason in error — read note before you resend anything.

Mark one message as read so later polls can skip it.

Delete every message in an inbox but KEEP the address.

Use between scenarios: the address stays registered wherever you already used it.

Delete an inbox and all its messages by address. Irreversible.

Delete a single message in an inbox by its id (the inbox itself stays).