Skip to main content

API Reference

The Generic Relayer API enables developers to integrate email-driven blockchain actions into their applications.

This API serves as the bridge between traditional email communication and blockchain transactions, allowing users to authorize and execute smart contract functions through email verification.

Submit Command​

Request Parameters​

contractAddress (string)

Address of your deployed smart contract containing the command.

dkimContractAddress (string)

Address of the DKIMVerification contract for email authentication.

accountCode (string)

A random uint256 value used to derive the user's address from their email address using CREATE2.

codeExistsInEmail (boolean)

Include accountCode in the email body (true or false).

functionAbi (object)

ABI of the function to execute.

commandTemplate (string)

Command string as defined in your contract (e.g., "Emit string {string}").

commandParams (array)

Parameters to fill into the command template.

templateId (string)

Unique identifier for the command template.

remainingArgs (array)

Additional arguments not included in the command template.

emailAddress (string)

Your email address where the command will be sent.

subject (string)

Subject line of the email.

body (string)

Body content of the email.

chain (string)

Blockchain network (e.g., "sepolia").

Response Fields​

message (string)

A confirmation message indicating the email has been sent.

request_id (string)

A unique identifier for the request.

status (string)

The status of the request. Possible value: "success".

Endpoint​

POST https://relayer.zk.email/api/submit

Request

Edit Request

Response

(Example)
{
  "message": "email sent",
  "request_id": "fecfac34-3333-4cd3-bdaa-1b349aea0699",
  "status": "success"
}

Request Status​

Request Parameters​

id (string)

UUID of the request to check status for.

Response Fields​

message (string)

A message indicating the request status.

request (object)

An object containing details about the request, including:

  • id (string): UUID of the request.
  • status (string): Current status of the request. Possible values include "Finished" and others.
  • updatedAt (string): ISO 8601 formatted timestamp of when the status was last updated.
  • emailTxAuth (object): Original request details including:
    • emailAddress: Recipient email address
    • subject: Email subject
    • body: Email body content
    • chain: Blockchain network
    • contractAddress: Smart contract address
    • dkimContractAddress: DKIM contract address
    • accountCode: Account code
    • codeExistsInEmail: Boolean indicating if code exists in email
    • functionAbi: ABI of the executed function
    • commandTemplate: Original command template
    • commandParams: Parameters used in the command
    • templateId: Template ID
    • remainingArgs: Additional arguments

Endpoint​

GET https://relayer.zk.email/api/status/:id

Request

Edit Request

Response

(Example)
{
  "message": "request status",
  "request": {"emailTxAuth":{"accountCode":"0x22a2d51a892f866cf3c6cc4e138ba87a8a5059a1d80dea5b8ee8232034a105b7","body":"Sending a hello world!","chain":"sepolia","codeExistsInEmail":true,"commandParams":["testing"],"commandTemplate":"Emit string {string}","contractAddress":"0xefb56bb5771cde84f487391b6c0f9ff1694d2631","dkimContractAddress":"0xc3f15f5cc76a86f97ef8bc2d5070b6725d8992ce","emailAddress":"saul.garces09@gmail.com","functionAbi":{"inputs":[{"components":[{"type":"uint256"},{"type":"bytes[]"},{"type":"uint256"},{"components":[{"type":"string"},{"type":"bytes32"},{"type":"uint256"},{"type":"string"},{"type":"bytes32"},{"type":"bytes32"},{"type":"bool"},{"type":"bytes"}],"type":"tuple"}],"internalType":"struct EmailAuthMsg","name":"emailAuthMsg","type":"tuple"},{"internalType":"address","name":"owner","type":"address"},{"internalType":"uint256","name":"templateIdx","type":"uint256"}],"name":"emitEmailCommand","outputs":[],"stateMutability":"nonpayable"},"remainingArgs":[{"Address":"0x9401296121fc9b78f84fc856b1f8dc88f4415b2e"},{"Uint":"0x0"}],"subject":"Hello World","templateId":"0x25d6c3eada7b2926c822bbfebfc3173123afb205cf093a8cae6622a56712f8a"},"id":"fecfac34-3333-4cd3-bdaa-1b349aea0699","status":"Finished","updatedAt":"2024-10-25T09:49:10.922319"}
}

Health Check​

Response Fields​

message (string)

A greeting message from the API.

status (string)

The status of the health check. Possible value: "success".

Endpoint​

GET https://relayer.zk.email/api/healthz

Request


Response

(Example)
{
  "message": "Hello from ZK Email!",
  "status": "success"
}