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. subdomain picks the part after the @ on mailflat.net (prefix@subdomain.mailflat.net); it needs a paid plan and is random when omitted. domain opens the inbox on a custom domain instead (prefix@acme.com). Pass it ONLY when the user named a domain they have already verified on this account; never guess one. Leave it empty and the address is created on mailflat.net. domain wins over subdomain.

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).

List the meetings on an inbox's calendar, soonest first.

Events come from calendar invitations this inbox received (Google Calendar, Outlook, ...). Each has an id, title, start/end in UTC, organizer, attendees, status ("confirmed" or "cancelled") and my_status (this inbox's answer: "needs-action", "accepted", "declined" or "tentative"). If the organizer moves a meeting, the event is updated in place and my_status goes back to "needs-action". Messages that carry an invitation also show it under calendar_event in read_messages.

Answer a calendar invitation: response is "accepted", "declined" or "tentative".

Sends a standard calendar reply email to the organizer, so their Google or Outlook calendar shows your answer. event_id comes from list_calendar_events (or calendar_event.event_id on a message). Call it ONCE per answer: the reply is queued like any email; use wait_until_sent with the returned message_id to confirm delivery.

Schedule a meeting from this inbox and email the invitations (you are the organizer).

Attendees get a normal invitation with Yes / No / Maybe buttons in Gmail, Outlook or Apple Calendar. Their answers show up in list_calendar_events under attendees[].status. start: ISO 8601 with an offset ("2026-10-06T14:00:00-04:00"), or without one plus timezone ("America/New_York"). Set end or duration_minutes (default 30 minutes). For an all-day event set all_day=true and use dates ("2026-10-06"); end is exclusive. message is a short note at the top of the invitation email. in_reply_to (a message's Message-ID) threads the invitation under an email you already exchanged. Call it ONCE per meeting: it emails every attendee. Normal send rules apply.

Change a meeting this inbox organized; attendees get the updated invitation.

Pass only what changes (empty = unchanged). Moving start keeps the duration. A new time resets every attendee's answer to "needs-action" (they are asked again). The same event is updated in their calendars, no duplicate. Invitations you RECEIVED cannot be changed here; answer those with rsvp_to_invite.

Cancel a meeting this inbox organized; it disappears from every attendee's calendar.

Read-only subscribe link for this inbox's calendar, to give to a human.

They add it in Google Calendar, Apple Calendar or Outlook and see this inbox's meetings there, with attendees and their answers. Calling again returns the SAME link, so sharing it twice never breaks a subscription. subscribe_links holds one-click add links per app. Google refreshes subscribed calendars every 8 to 24 hours; for live state use list_calendar_events.

Replace this inbox's calendar subscribe link; the old link stops working at once.

Use only when the link leaked. Everyone subscribed has to add the new link.